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

# Octopia

> Connect Octopia to Redo to create returns automatically and process them once the Octopia warehouse receives them

## What is Octopia?

Octopia is a marketplace and fulfillment platform. Its fulfillment service stores and ships your orders and receives returned parcels at its warehouse. Redo's Octopia integration creates a return in Octopia for each approved return and processes the return in Redo once the Octopia warehouse receives the items.

## What the integration does

### From Redo to Octopia

When a return is approved in Redo, the integration creates one **Octopia return** for each outbound shipment the returned items shipped in. Each Octopia return has:

* **Outbound shipment**, found by the Shopify order name, then by the name without the `#`. If you set a **Sales channel name**, only that channel's shipments are searched.
* **Return lines**, matched to the shipment's items by SKU, barcode, product ID, or variant ID. Units that other Octopia returns on the shipment already claim are left out. Items the customer keeps (green returns) are left off.
* **Return reason**, mapped from the return reason in your return flow. When a reason has no mapping, Redo sends your **Default return reason**.
* **Comment** `Redo return {returnId}`, which Redo uses to recognize its own Octopia returns. Redo reuses an Octopia return that already has the comment instead of creating a second one.

Redo does not create an Octopia return when:

* the return is cancelled
* every item is a green return
* the return is an in-store (POS) return
* the return is not routed to Octopia (see the **Route returns to Octopia** step in [How to set it up](#how-to-set-it-up))
* **Create returns** is turned off

Redo does not send a tracking number and does not create a label in Octopia. After creation, Redo reads the Octopia parcel number and records it on the return. If Octopia has not assigned the number yet, the next sync records it.

### From Octopia to Redo

Octopia does not send webhooks. Redo checks Octopia **every 15 minutes** for every open return linked to an Octopia return.

| Octopia return status | What Redo does |
| - | - |
| Pending (part of the return arrived) | Processes the products Octopia received in full. Restocking is off. |
| Completed | Processes the products Octopia received in full. If items are still missing, Redo flags the return once. |
| Any other status | Records the parcel number if it is new and changes nothing else. |

Redo processes only when **Process returns** is on. It matches received quantities to your products through the shipment's items. If Octopia no longer has a linked return (a 404), Redo flags the return. Redo does not process returns with the status **Needs review** or **Flagged**.

If Octopia rejects your credentials during a check, Redo skips your team for that run. The next check tries again.

### What Redo does not do

* Redo does not cancel or reject the Octopia return when a return is reset or rejected in Redo. Cancel it in Octopia.
* Redo does not create blind returns, which are returns without an order in Octopia.
* Redo does not create one Octopia return for a Redo return that spans several orders. That return gets the error `OCTOPIA_MULTIPLE_ORDERS`.

## How to set it up

### Prerequisites

> [accordion] Octopia seller account with API access
>
> You need an Octopia seller account, and your orders must reach Octopia with the Shopify order name as the order reference.

> [accordion] Client ID and client secret
>
> Create them in Octopia under API credentials management. Redo stores the secret encrypted and shows only its last four characters after you save.

> [accordion] Seller ID
>
> Your numeric Octopia seller ID.

> [accordion] Permission
>
> You need the permission to change returns and claims settings in Redo.

### Configuration steps

**1. Open the Octopia card**

Go to **Settings → Integrations → Octopia**. In the **Returns** row, click **Connect**.

**2. Enter your credentials**

Fill in:

* **Client ID**
* **Client secret**
* **Seller ID** (numbers only)
* **Sales channel name** (optional, up to 100 characters). Set it when several stores share one Octopia seller account, so Redo matches only this store's shipments.

**3. Set return reasons**

Choose a **Default return reason** (the default is **Changed mind**). Under **Return reason mapping**, map each reason in your return flow to an Octopia reason: **Damaged**, **Missing item**, **Delivered more than once**, **Wrong item**, **Changed mind**, or **Defective**.

**4. Choose what to turn on**

Both are on by default:

* **Create returns:** Redo creates a return in Octopia when a return is approved.
* **Process returns:** Redo processes returns when the Octopia warehouse receives them.

**5. Save**

Click **Connect**. Redo tests the credentials with a live request to Octopia. If Octopia refuses them, Redo shows "Octopia rejected the client ID, client secret or seller ID." and does not save. After you connect, **Save** applies later changes, **Manage** opens the settings, and **Disconnect** removes the connection.

**6. Route returns to Octopia**

A return goes to Octopia only when its shipment group, or its return address, uses the Octopia return hub. In the settings for the return address, choose **Octopia** as the external return hub.

**7. Test the integration**

Create a test return for an order that is in Octopia, then:

1. Approve the return and confirm the return timeline shows the Octopia return.
2. In Octopia, check the return lines and reason.
3. Receive the parcel in Octopia.
4. Within 15 minutes, confirm Redo processes the return.

## Testing

Octopia has no public sandbox. Test with a real order in your seller account.

## Support

For issues with the Redo integration configuration, return processing, or data synchronization, contact **[support@getredo.com](mailto:support@getredo.com)**.

For issues with Octopia access, API credentials, or warehouse operations, contact your Octopia account manager or support team.


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