> ## 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.

# 8returns

> Check returns in the inbox and register returns with AI Agents.

The 8returns integration brings return status, returned items, and shipment details into Chatarmin CX so your team can answer return questions from a ticket. AI Agents can also register a return and request a shipping label and tracking number.

## When to use it

Use 8returns to answer "what is happening with my return?" questions or help a customer register the items they want to send back. Your team can read existing return information in the inbox; creating a return is available through AI Agent actions.

## Set up 8returns

You need the **API Key** and **Password** for your 8returns API connection. The integration links to the [8returns public API page](https://dashboard.returnsportal.online/integrations/public_api).

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

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

  <Step title="Connect the account">
    Click **Connect** to open the credential form, enter the **API Key** and **Password**, then click **Connect** to save. cx checks the credentials against 8returns before saving the connection. A successful connection shows **Connected**.
  </Step>

  <Step title="Check an existing return">
    Open a ticket whose contact has the email address used on an existing 8returns return. Expand the **8returns** card in the customer panel and check the order number and return status. This lookup does not create or change a return.
  </Step>
</Steps>

## Use 8returns in the inbox

cx looks up returns using the ticket contact's **email address**. In the customer panel, expand the connected 8returns card to see:

* the order number and return status
* item names and quantities, plus return reasons when available
* carrier and tracking number when 8returns provides them

When a label URL is available, clicking the tracking number opens the **shipping label**, not a carrier tracking page. Returns without tracking details still show their status and items. The card initially shows three returns; use the button below them to show more results.

<Note>
  The inbox card is read-only. It has no button to register a return or generate a label. Use the AI
  Agent action below for those changes.
</Note>

| Situation | What you see |
| - | - |
| Contact has no email | A prompt to add an email to look up returns |
| No matching returns | "No 8returns returns found for this customer" |
| Connection is misconfigured | A configuration error rather than an empty return list |
| Lookup fails | "Could not load 8returns returns" |

## AI Agent actions

Connect 8returns first, then [open AI Agents](https://armin.cx/app/_/ai/agents-v2), choose your agent, and enable the relevant [actions](/ai-agents/skills-and-actions). Select the connected 8returns account(s) the agent may use.

### Get 8returns return

This read-only action finds returns by **order number** or **customer email** and returns status, items, and available shipment details, including tracking, carrier, and label URL. It does not require human approval.

Use the order number when the customer supplies one. Otherwise, use their email instead of asking for an order number just to look up a return. If both are supplied, the lookup uses the order number. Lookups use the first 50 search results from 8returns, newest first, and keep exact order-number or email matches; they are not a complete historical export.

### Create 8returns return

This action registers a return in 8returns using:

* the **shop order number**
* every item the customer wants to return, identified by **SKU** and **quantity**
* an explicit choice of whether to generate a shipping label

<Warning>
  Submit the complete intended item list in one call. The action warns that, for an existing open
  return on the order, items omitted from the request will be marked missing.
</Warning>

To request a label and tracking number in the same call, configure **Return method ID** on the action using the method ID from your 8returns dashboard, and instruct the agent when to request a label. The action requests it with `generateLabel: true`.

To register a return without a label, use `generateLabel: false`. You can leave **Return method ID** empty for that use. If the agent requests a label without a configured method ID, the action fails before registering the return; it does not silently fall back to a return without a label.

**Create 8returns return** requires [human approval](/ai-agents/human-in-the-loop) by default. You can adjust approval on the action, but keep it required while reviewing your returns process.

<Warning>
  The action does not show a label price or collect return postage from the customer. Do not assume
  labels are free. Confirm your label costs separately and give the agent clear instructions about
  who pays and when it may request a label.
</Warning>

### Check the result before replying

A return can be registered even if its label request fails. Check the item results and label result before telling the customer that their return or label is ready. A successful label result includes the tracking number and carrier; a label URL is only available when 8returns supplies one.

The create action suppresses 8returns' automatic customer notification email. Registering a return does not email the label to the customer. Enable a reply action and tell the agent how to communicate the confirmed result, or hand the ticket to your team if a usable label is missing.

## Best practices

* Give the agent your return eligibility policy and escalation rules. The create action does not itself check your return window or issue a refund.
* Confirm the order number, SKUs, quantities, and complete item list before approving a return.
* Use **Get 8returns return** for a read-only check before enabling writes. Do not create a live return just to test the connection.
* If label creation fails after registration, inspect the existing return in 8returns before retrying. Do not treat it as though no return exists.

## Disconnect 8returns

In [integrations](https://armin.cx/app/_/settings/integrations), open the account's **Connected** menu, choose **Disconnect**, and confirm **Delete** to remove the connection. This is not an action to cancel an existing return in 8returns.

## Troubleshooting

### Connection fails

Check both API credentials. cx reports **"We couldn't connect to 8returns. Please check your API Key and Password."** when authentication is rejected.

### A return does not appear

Check that the ticket contact's email matches the customer email on the return and that you connected the correct 8returns account. Use the AI lookup by order number to check a specific order. The inbox cannot search a contact without an email.

### A label is missing

Check whether the agent requested a label and whether **Return method ID** is configured. Review the action result: the return may exist even when the label failed, and a tracking number does not guarantee a label URL.

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


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