> For the complete documentation index, see [llms.txt](https://alhena.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://alhena.gitbook.io/docs/integrations/ecommerce/orders-shipping-returns/integrating-alhena-ai-with-loop.md).

# Loop

Integrate Alhena with Loop to let your AI assistant handle returns and exchanges — eligibility checks, return creation, status lookups, and variant swaps — directly in chat.

## Prerequisites

* A Loop merchant account with admin access
* A Loop API key (instructions below)

## Getting Your API Key

### Step 1: Create an API Key in Loop

1. Log in to your **Loop admin**
2. Go to **Returns Management > Tools & integrations > Developer Tools**
3. Click **Generate API key**
4. Give the key a recognizable name (e.g. `Alhena`)

### Step 2: Configure Key Scopes

Grant the API key the following scopes. Each one unlocks a specific group of customer-facing return actions.

| Scope      | What it enables                                                                                       |
| ---------- | ----------------------------------------------------------------------------------------------------- |
| **Order**  | Look up the customer's order to determine which items are eligible for return or exchange             |
| **Return** | Read the status of existing returns, open new returns, and process exchanges on the customer's behalf |

{% hint style="warning" %}
Both **Order** and **Return** scopes are required. Without **Order**, eligibility lookups fail. Without **Return**, Alhena cannot read statuses or open returns and exchanges.
{% endhint %}

### Step 3: Copy the API Key

After generating, Loop will display the API key once. Copy it immediately — it won't be shown again.

{% hint style="warning" %}
The API key is only displayed once when you create it. If you lose it, you'll need to generate a new key.
{% endhint %}

***

## Setup

### Step 1: Enable Loop in Alhena

1. In Alhena, go to **Settings > Integrations**
2. Find **Loop** and click **Enable**
3. You'll be taken to the Loop configuration page

### Step 2: Connect Your Store

1. Paste your **Loop API Key** into the API key field
2. Click **Connect**

Alhena will verify the key with Loop and confirm the connection. If the key is invalid, you'll see an error explaining what's wrong.

{% hint style="info" %}
Alhena verifies the key by calling Loop's return details endpoint. A `401 Unauthorized` response means the key is invalid or revoked — generate a fresh one in Loop and try again.
{% endhint %}

***

## Enabled Agents and Capabilities

When you connect Loop, return-aware capabilities are added to your **Return Management Agent**. Only **Get Return Status** is enabled by default — it's read-only and safe to expose immediately. The mutating capabilities (creating returns, creating exchanges) and the eligibility check are opt-in from **AI Settings > Agents** so you control exactly what your AI is allowed to do.

### Return Management

| Capability                   | Description                                                                                    | Default on connect |
| ---------------------------- | ---------------------------------------------------------------------------------------------- | ------------------ |
| **Get Return Status**        | Check the status of an existing return — received, in transit, refunded, exchange shipped      | **Enabled**        |
| **Check Return Eligibility** | Look up which items in an order are eligible for return based on your return policy and window | Disabled (opt-in)  |
| **Create Return**            | Open a return on the customer's behalf for one or more eligible items                          | Disabled (opt-in)  |
| **Create Exchange**          | Process an exchange for a different variant — different size, color, or style                  | Disabled (opt-in)  |

You can enable or disable individual capabilities in **AI Settings > Agents**.

***

## What your customers can ask

Once connected, your AI assistant can help customers with:

### Return eligibility

* "Can I return my order?"
* "What items in my order are eligible for return?"
* "Is this t-shirt returnable?"

### Creating a return

* "I want to return the blue medium shirt from order #1001"
* "Start a return for my last order"

### Return status

* "What's the status of my return?"
* "Did my refund process yet?"
* "Has my return been received?"

### Exchanges

* "I want to exchange this for a different size"
* "Can I swap the red one for the blue one?"
* "I want to exchange this t-shirt for the same one in medium"

{% hint style="info" %}
Mutating actions like creating a return or processing an exchange are gated behind agent guidelines that ask the customer to confirm before Alhena commits the change. You can tighten or relax these guidelines on the agent settings page.
{% endhint %}

***

## Loop and Shopify together

Most Loop merchants are also on Shopify. When both are connected, Alhena routes correctly:

* **Return and exchange questions** ("can I return this?", "start a return", "what's the status of my return?", "I want a different size") → Loop capabilities
* **Order lookup** ("where is my order #12345?") → Shopify capabilities
* **Shipment tracking** ("has it shipped yet?") → Shopify capabilities
* **Order cancellation** ("cancel my order, it hasn't shipped") → Shopify capabilities

You don't need to configure anything — the agents pick the right capability based on the customer's question.

***

## Disconnecting

To disconnect Loop:

1. Go to **Settings > Integrations > Loop**
2. Click **Disconnect**
3. Confirm the disconnection

This disables all Loop-connected capabilities and revokes Alhena's access to your Loop data. Your returns in Loop are unaffected.

***

## Troubleshooting

### "Invalid Loop API key" or 401 error

* Verify the key is correct and hasn't been revoked in **Loop > Returns Management > Tools & integrations > Developer Tools**
* API keys are case-sensitive — copy-paste carefully, no leading or trailing whitespace
* If the key was rotated in Loop, generate a fresh one and reconnect from Alhena

### Eligibility checks fail or return nothing

* The API key is likely missing the **Order** scope
* In Loop, regenerate the key with both **Order** and **Return** scopes selected, then reconnect from Alhena

### "Failed to create return" or "Failed to create exchange"

* The API key is likely missing the **Return** scope
* Confirm the items are still within your return window and match your return policy in Loop — items outside the window cannot be returned even with a valid key
* Confirm the variant the customer is exchanging into is in stock — Loop will reject exchanges to out-of-stock variants

### Capabilities don't appear on the Return Management Agent page

* After connecting Loop, refresh the agent settings page
* If only **Get Return Status** is showing, that's expected — every other Loop capability is opt-in. Enable the ones you want from the capability toggles on the agent page.

### Return status lookups return nothing for a known return

* Confirm the return exists in **Loop > Returns** and is associated with the order or email the customer is giving
* Returns that were started outside Loop (e.g. issued as a manual refund) won't be visible through the API