> ## Documentation Index
> Fetch the complete documentation index at: https://docs.armin.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Loop Returns

> Let AI Agents check return status, return method, and refund status from Loop Returns.

The Loop Returns integration lets your AI Agents answer "where is my return, and has my refund gone through?" without handing the ticket to your team. The agent looks up the return in Loop Returns and replies with its status, return method, shipping label progress, returned items, and refund status.

<Note>
  This page is about **Loop Returns** (loopreturns.com), the returns and exchanges platform. For the subscription app, see [Loop](/integrations/loop). They are separate integrations with separate API keys.
</Note>

## When to use it

Use Loop Returns to automate return questions such as:

* "Did you receive my return?"
* "Where is my return label?"
* "Has my refund been issued?"
* "Why was my return rejected?"

The integration is read-only. It does not create, approve, or change returns in Loop.

## Set up Loop Returns

You need a Loop Returns API key with the **Returns** scope.

<Steps>
  <Step title="Create an API key in Loop">
    In the [Loop Admin](https://admin.loopreturns.com), go to **Returns Management** → **Tools & integrations** → **Developer Tools**. Click **Generate API key**, add the **Returns** scope, give the key a name such as "Chatarmin CX", and click **Generate**. Copy the key.

    A key without the Returns scope cannot read returns, and cx will not save it.
  </Step>

  <Step title="Open integrations">
    [Open integrations](https://armin.cx/app/_/settings/integrations) in your workspace settings and choose **Loop Returns**.

    If Loop Returns is not listed, contact your Chatarmin CX account team to check availability for your workspace.
  </Step>

  <Step title="Connect the account">
    Click **Connect**, paste the **API Key**, and click **Connect** to save. cx checks the key against Loop Returns before saving it. A successful connection shows **Connected**.

    cx stores the key encrypted.
  </Step>

  <Step title="Enable the action on an agent">
    [Open AI Agents](https://armin.cx/app/_/ai/agents-v2), choose your agent, and enable **Get Loop Returns return** in its [actions](/ai-agents/skills-and-actions). Select the connected Loop Returns account the agent may use.
  </Step>
</Steps>

## AI Agent action

### Get Loop Returns return

This read-only action finds a return by **order number** or **Loop return ID**. It does not need [human approval](/ai-agents/human-in-the-loop).

The agent gets back:

* the return state: open, review, closed, cancelled, or expired
* the return method and the label and tracking status
* the returned items with the customer's return reasons
* the refund amount and a refund status

Customers write order numbers with or without the `#`, for example `1001` or `#1001`. The action tries both.

<Warning>
  Loop Returns cannot be searched by email. If the customer only gives an email address, the agent needs to find the order number first, for example with your [Shopify](/integrations/shopify) integration, and then look up the return. Write this into the agent's instructions.
</Warning>

### Who can see which return

On a ticket, the agent only gets returns whose customer email matches an email address on the ticket's contact. If the order number belongs to someone else, the action answers "not found". This stops a customer from reading another customer's return by guessing an order number.

Test runs without a ticket do not have a customer to compare with, so the email check does not apply there. Use a test return when you try it.

### What the refund status means

Loop does not send a refund status. cx works it out from the return, so the agent is told to say a refund was issued **only** when the status is `processed`.

| Refund status | Meaning |
| - | - |
| `processed` | Loop lists a refund for this return. The money has been sent. |
| `pending` | The return is open or in review and a refund amount is expected, but no refund exists yet. |
| `not_issued` | The return was cancelled or expired. No refund was issued. |
| `no_refund` | The refund amount is zero, for example for an exchange or store credit. |
| `unknown` | cx cannot tell. For example, the return is closed with an amount but Loop lists no refund. |

When the status is `unknown`, the agent should not promise a refund. Tell it to hand the ticket to your team.

## Best practices

* Tell the agent when to look up a return and what to say for each state, such as "label created but not shipped" or "received, refund pending".
* Tell the agent to ask for the order number if the customer does not give one.
* Keep an escalation rule for `unknown` and for returns that cannot be found.
* Use a test return from your own order for the first check. Do not use a real customer's order.

## Safe test

<Steps>
  <Step title="Pick a known return">
    Choose a return in Loop that you can see in the Loop Admin. Note its order number and state.
  </Step>

  <Step title="Run the agent in a test">
    Ask the agent in a test run about that order number, for example "What is the status of my return for order #1001?"
  </Step>

  <Step title="Compare">
    Check that the state, tracking, items, and refund status match the Loop Admin. The lookup does not change anything in Loop.
  </Step>
</Steps>

## Disconnect Loop Returns

In [integrations](https://armin.cx/app/_/settings/integrations), open the account's **Connected** menu, choose **Disconnect**, and confirm **Delete**. cx removes the stored key. Agents that used the account can no longer look up returns.

To stop access on the Loop side too, delete the API key in the Loop Admin under **Developer Tools**.

## Troubleshooting

### Connection fails with "check your API Key"

Check that you pasted the full key and that it was created for the correct Loop shop. cx shows **"We couldn't connect to Loop Returns. Please check your API Key."** when Loop rejects the key.

### Connection fails because of the scope

cx shows **"This Loop Returns API Key cannot read returns."** Loop can also report a key without the right scope as an invalid key, so if the invalid-key message persists with a correct key, check its scopes too. Create a new key with the **Returns** scope in Loop Developer Tools and connect again.

### "We couldn't reach Loop Returns"

Loop did not answer. The key may be fine. Wait a moment and try again. If it keeps failing, check [Loop's status page](https://status.loopreturns.com).

### The agent says it cannot find a return

Check that:

* the order number is the shop order number, for example `1001`
* the return exists in the Loop Admin
* the customer's email on the return matches an email on the ticket's contact
* the agent has the Loop Returns account selected on the action

### A refund shows as unknown

Open the return in the Loop Admin and check whether a refund was issued. If it was, contact your Chatarmin CX account team.

If the connection or action still fails, contact your Chatarmin CX account team with the error message and the step that failed. Do not include your API key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.