curl --request POST \
  --url https://api.cubbo.com/v1/returns \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "store_id": 1234,
  "order_number": "ORD-0001",
  "notes": "Customer changed their mind",
  "products": [
    {
      "sku": "SKU-RED-M",
      "quantity": 1
    }
  ]
}
'

{
  "id": 98765,
  "status": "PENDING",
  "return_type": "TO_BE_DETERMINED",
  "notes": "Customer changed their mind",
  "externally_requested": true,
  "expected_products": [
    {
      "product_id": 5551,
      "quantity": 1,
      "skus": [
        "SKU-RED-M"
      ]
    }
  ],
  "created_at": "2026-10-12T15:04:05.123Z",
  "order_number": "ORD-0001"
}

Returns

Request a return for a shipped order

Creates a return request for an order your store already shipped. By default the return is created as TO_BE_DETERMINED in status PENDING: it records what the customer says is coming back and waits to be reviewed (resolved) by Cubbo or by you. If you already know the outcome, set return_type to SIMPLE_RETURN or EXCHANGE and the return is resolved in the same call: the order moves to returning, the return moves to REQUESTED, the return instructions (RMA document) are generated and emailed to the customer, and optionally a prepaid return shipping label is booked with the carrier.

The order must belong to store_id, be in status shipped, must not be a pick-and-ship order, and must not already have an active (non-cancelled) return.
Omit products (or send []) for a full return: every ordered item at its full ordered quantity. Otherwise list the SKUs and quantities coming back; repeated SKUs are summed.
Kits cannot be returned or exchanged; list the individual products instead.
generate_guide is required whenever return_type is not TO_BE_DETERMINED. Send false to resolve without booking a return shipping label (the RMA is still generated).
For EXCHANGE, exchange_products lists the replacement items (resolved against your store catalog, not the order) and their stock is reserved right away, to ship once the return arrives.
Return-level blockers (order not shipped, return already exists) are reported before item-level errors.
If the return is created but the immediate resolution fails (for example the carrier rejects the label), the return stays PENDING / TO_BE_DETERMINED and the error is returned; fetch it with GET /returns/{return_id} before retrying, since a second call would answer RETURN_ALREADY_EXISTS.
Your API credentials need the permission to create returns; ask Cubbo support if the call answers 401 with a valid token.

POST

returns

curl --request POST \
  --url https://api.cubbo.com/v1/returns \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "store_id": 1234,
  "order_number": "ORD-0001",
  "notes": "Customer changed their mind",
  "products": [
    {
      "sku": "SKU-RED-M",
      "quantity": 1
    }
  ]
}
'

{
  "id": 98765,
  "status": "PENDING",
  "return_type": "TO_BE_DETERMINED",
  "notes": "Customer changed their mind",
  "externally_requested": true,
  "expected_products": [
    {
      "product_id": 5551,
      "quantity": 1,
      "skus": [
        "SKU-RED-M"
      ]
    }
  ],
  "created_at": "2026-10-12T15:04:05.123Z",
  "order_number": "ORD-0001"
}

Authorizations

Authorization

string

header

required

Token returned by POST /auth/token, sent as Authorization: Bearer <token>.

Body

application/json

store_id

integer

required

Id of the store that owns the order.

Example:

1234

order_number

string

required

Order number of the shipped order to return.

Example:

"ORD-0001"

notes

string

required

Reason for the return or any comment to keep with it. Shown on the return instructions sent to the customer when the return is resolved.

Example:

"Customer changed their mind"

products

object[]

Items coming back, by SKU. Omit or send an empty array for a full return of every ordered item at its full quantity. Repeated SKUs are summed. Each SKU must be on the order, map to a single product and not be a kit; the quantity cannot exceed the ordered quantity.

Show child attributes

return_type

enum<string>

default:TO_BE_DETERMINED

Outcome of the return. TO_BE_DETERMINED (default) creates a pending request to be reviewed later. SIMPLE_RETURN and EXCHANGE resolve the return immediately (order moves to returning, return instructions are emailed to the customer).

Available options:

TO_BE_DETERMINED,

SIMPLE_RETURN,

EXCHANGE

Example:

"TO_BE_DETERMINED"

generate_guide

boolean

Required when return_type is SIMPLE_RETURN or EXCHANGE; ignored otherwise. true books a prepaid return shipping label with the carrier and attaches it to the return instructions; false resolves the return without a label.

Example:

true

exchange_products

object[]

Required when return_type is EXCHANGE; ignored otherwise. Replacement items to ship once the return arrives, by SKU of your store catalog (kits not allowed). Their stock is reserved immediately.

Show child attributes

Response

Return created. Only the listed fields are returned; exchange_products is present only for EXCHANGE returns.

Response of POST /returns.

integer

required

Unique id of the return. Use it with the other returns endpoints.

Example:

98765

status

enum<string>

required

Lifecycle status of a return.

PENDING: created and waiting for a decision (review of a customer request, or decision on an order returned by the carrier).
REQUESTED: resolved; the customer has the return instructions and the goods are expected back.
ORDERED: resolved by creating a new (replacement or resend) order.
CANCELLED: cancelled before the goods came back; reserved stock was released.
ARRIVED_AT_WAREHOUSE: the package arrived at the warehouse and is waiting to be processed.
AWAITING_INSPECTION: the package was opened and is waiting for inspection of its contents.
RECEIVED: the goods were checked in and are being re-entered into inventory.
REENTERED: the goods were fully re-entered into inventory; the return is complete.
UNSUCCESSFUL: closed without receiving anything; every expected product was missing on reception.

Available options:

PENDING,

REQUESTED,

ORDERED,

CANCELLED,

ARRIVED_AT_WAREHOUSE,

AWAITING_INSPECTION,

RECEIVED,

REENTERED,

UNSUCCESSFUL

Example:

"PENDING"

return_type

enum<string>

required

What kind of return this is.

TO_BE_DETERMINED: requested by the customer or by you, not yet reviewed; the outcome (simple return, exchange, rejection) is decided later.
SIMPLE_RETURN: the customer sends the goods back; no replacement is shipped.
EXCHANGE: the customer sends the goods back and replacement items (exchange_products) are reserved to ship once the return arrives.
IMMEDIATE_EXCHANGE: replacement items ship right away, before the return arrives (created from the Cubbo app, not through this API).
RETURNED_BY_CARRIER: the carrier could not deliver the order and brought it back; decide it with POST /returns/{return_id}/decision.
UNIDENTIFIED: a package arrived at the warehouse that could not be matched to an order (created by warehouse staff).

Available options:

TO_BE_DETERMINED,

SIMPLE_RETURN,

EXCHANGE,

IMMEDIATE_EXCHANGE,

RETURNED_BY_CARRIER,

UNIDENTIFIED

Example:

"TO_BE_DETERMINED"

notes

string

required

The notes you sent.

Example:

"Customer changed their mind"

externally_requested

boolean

required

Always true for returns created through the API.

Example:

true

expected_products

object[]

required

Resolved products and quantities coming back, with their SKUs.

Show child attributes

created_at

string<date-time>

required

When the return was created.

Example:

"2026-10-12T15:04:05.123Z"

order_number

string

required

The order number you sent.

Example:

"ORD-0001"

exchange_products

object[]

Replacement products with their SKUs. Only present for EXCHANGE returns.

Show child attributes

Authentication

Orders

Click and collect

Inventory

Lots

Shipping labels

Replenishments

Reports

Returns

Shipping methods

Stores

Webhooks

Request a return for a shipped order

Authorizations

Body

Response