Returns

A parcel received back at the store's warehouse goes through the store's existing return flow. The integration reports that return with return.created and accepts POST /returns for items the store sold.

Every store is on both sides of this. As the shipping shop it reports returns that arrive at its warehouse. As the selling shop it receives returns through POST /returns for items it sold that another shop shipped.

1. The online store sends `return.created`

Send it once, when the goods are back and the return has been processed in the store's own system. Not when the customer announces a return, and not when a label is made.

The store's platform. Sends one return.created with a unique event_id, the shipping order id and every returned line.
SKUU. Checks the signature, finds the shipping order and stores the return.
SKUU. Answers 200. An unknown order or line receives 404; an incomplete line receives 422 partial_quantity. See Errors and retries.

Example: the return.created event

{
  "spec_version": "1",
  "event": "return.created",
  "event_id": "evt_return_01JABC",
  "occurred_at": "2026-09-07T09:00:00Z",
  "data": {
    "order_id": "5001",
    "external_ref": "skuu-order-01JABC",
    "lines": [
      {
        "order_line_id": "SHIPPING-LINE-1",
        "external_ref": "skuu-line-01JABC",
        "quantity": 1,
        "reason": "too_small"
      }
    ],
    "customer_note": "Received, unworn."
  }
}

All fields in `data`

Field in `data`	Required	What it means
`order_id`	Required	The `order_id` returned from `POST /orders`. Finds the order.
`lines[]`	Required	Every returned line.
`lines[].order_line_id`	Required	The store's own line id.
`lines[].external_ref`	Required for a shipping order	SKUU's line reference from that order, the same value sent in `fulfillment.shipped`. Finds the line.
`lines[].quantity`	Required	The full quantity of the line.
`external_ref`	Optional	SKUU's order reference from that order. SKUU checks it against the order.
`lines[].reason` · `customer_note`	Optional	Passed to SKUU customer service.

Use the same event_id and identical bytes for a retry; there is no return_id in this event. The selling platform can also report an existing return on its seller order, using its own order_line_id values and omitting SKUU line references. SKUU records it for its current return-processing flow; it does not refund on event receipt.

2. SKUU calls `POST /returns`

When the customer returns an item that another shop shipped, SKUU registers the processed return on the seller order. Each request belongs to one order; separate returns can create separate requests.

SKUU. Calls POST /returns on the store's API with the store's own order and line ids from order.created.
The store's platform. Creates the return and answers with the store's stable return_id. Refund the customer from there, through the store's own return flow, automatically where it is set up that way.
The store's platform. The same external_ref again returns the same return_id and creates nothing. Different data under the same reference is a 409.

Example: the return request

POST {your_api_root}/returns

{
  "external_ref": "skuu-return-01JABC",
  "order_id": "ORD-10045",
  "lines": [
    {
      "order_line_id": "LINE-1",
      "quantity": 1,
      "reason": "too_small"
    }
  ]
}

All fields in the request

Field in the request	Always present	What it means
`external_ref`	Yes	SKUU's reference for this return and the idempotency key.
`order_id`	Yes	The store's order id from `order.created`.
`lines[].order_line_id`	Yes	The store's `line_item_id` from `order.created`, so the store knows which item to refund.
`lines[].quantity`	Yes	The full quantity of the line.
`lines[].reason`	No	Why the customer returned it, when known.

{
  "external_ref": "skuu-return-01JABC",
  "return_id": "RET-1001"
}

The response, field by field

Field in the response	What it must be
`external_ref`	The reference from the request, unchanged
`return_id`	The store's stable id for the created return

Return 200 with both required references. Additional response fields are ignored. SKUU retries 429, 5xx and timeouts three times; any other 4xx stops and alerts SKUU customer service, who sends the same request again once it is fixed.

SKUU has not built an automatic refund instruction yet. For SKUU to initiate refunds instead, discuss the integration and setup with the SKUU contact. It cannot currently be enabled as an existing API setting. The store's own platform can already attach its own refund logic to POST /returns.

The next page is Go live. The exact contract is on Send an event and Create a return on an order.

1. The online store sends return.created

2. SKUU calls POST /returns

1. The online store sends `return.created`

2. SKUU calls `POST /returns`