Skip to content

Returns

A return records goods sent back by the customer against a shipped fulfillment order. It lists the returned items and the amounts to settle, and — when the customer asked for an exchange — the replacement order created for it.

Every return waits for a credit memo from the ERP. Registering the credit memo completes the return (see the ERP integration guide).

EndpointPurposeACL resource
GET /V1/returnsList returns, 100 per pageShipper_ShipmentReturn::api_returns_list
GET /V1/returns/{incrementId}Fetch one return by its numberShipper_ShipmentReturn::api_returns_get
GET /V1/returns/pending_creditmemoList returns awaiting a credit memoShipper_ShipmentReturn::api_returns_pending_creditmemo
POST /V1/return/creditmemoRegister the credit memo and complete a returnShipper_ShipmentReturn::api_return_creditmemo
GET /rest/{store_code}/V1/returns?status=complete&page=1&date=2026-10-30%2000:00:00
Authorization: Bearer <your-token>
Accept: application/json

Query parameters — all optional, and combinable:

ParameterDescription
pagePage number, starting at 1. Page size is fixed at 100; iterate until you receive an empty array.
dateyyyy-mm-dd hh:mm:ss — only returns updated at or after this time.
channelSales channel code — only returns of orders from that channel.
statusOnly returns in this status (see Statuses).

Returns are listed in creation order (oldest first). An invalid page or date returns 400.

See GET /V1/returns for the full schema.

GET /rest/{store_code}/V1/returns/R000000123
Authorization: Bearer <your-token>
Accept: application/json

{incrementId} is the return number — the return_number field of the response. An unknown number returns 404.

See GET /V1/returns/{incrementId}.

GET /rest/{store_code}/V1/returns/pending_creditmemo?page=1
Authorization: Bearer <your-token>
Accept: application/json

Lists every return in status pending, with the same data as GET /V1/returns. Accepts page, date and channel like the returns list. All returns pass through this queue, whatever their settlement type — a return on which the customer owes the difference is listed as well. A return leaves the queue once its credit memo is registered.

See GET /V1/returns/pending_creditmemo.

POST /rest/{store_code}/V1/return/creditmemo
Authorization: Bearer <your-token>
Content-Type: application/json
{
"creditmemo": {
"return_id": "R000000123",
"creditmemo_number": "CN-2026-000045",
"creditmemo_time": "2026-10-30T11:41:43+00:00",
"items": [
{ "item_id": 812, "qty": 1 },
{ "item_id": 813, "qty": 2 }
],
"shipping_amount_incl_tax": 4.99
}
}

Request fields:

  • return_id — required. The return number (return_number); the return id is accepted as well. An unknown return returns 404.
  • creditmemo_number — required. Your credit memo number. It must be unique: a number already registered for another return returns 400.
  • creditmemo_time — optional, ISO 8601 with offset (yyyy-mm-ddThh:mm:ss+hh:mm).
  • additional_data — optional JSON-encoded string with extra data to store on the credit memo.
  • doc_binary — optional, the credit memo document to attach: the PDF file content, base64-encoded. Anything that does not decode to a PDF returns 400 ("doc_binary": "Invalid content, expected a base64 encoded PDF document").

Two validation fields must match the return as listed in pending_creditmemo:

  • items[] — required; must list every item of the return, each with its returned qty. item_id is the return item id. A missing, extra or repeated item, or a different qty, returns 400.
  • shipping_amount_incl_tax — required; the shipping of the original order refunded with the return, including tax. Use the return_shipping_amount returned for the return; it is 0 when the return does not include shipping.

These fields only guard against a stale snapshot — they do not change what is credited. The credit memo always covers the return exactly as recorded in ShipperOne.

A successful call completes the return and responds with it, now carrying status: complete, creditmemo_number, creditmemo_time and completed_at.

Idempotency — re-sending the credit memo of a completed return with the same creditmemo_number returns the return without re-processing. A different creditmemo_number for a completed return returns 400.

See POST /V1/return/creditmemo.

StatusMeaning
draftBeing prepared in ShipperOne — not yet waiting for a credit memo.
pendingAwaiting the credit memo — listed in pending_creditmemo.
completeFinal — the credit memo is registered and the return can no longer be edited.

To book completed returns, poll status=complete together with date set to the time of your previous run.

settlement_type tells which way the money goes, from the sign of settlement_total:

Valuesettlement_totalMeaning
refundpositiveMoney goes back to the customer.
chargenegativeThe customer pays the difference — the replacement is worth more than what was returned.
nonezeroNothing to settle — e.g. an even exchange.

How each type is settled is up to your accounting; every return gets a credit memo either way.

A return links to every document it relates to:

  • fulfillment_order_id / fulfillment_order_number — the fulfillment order the goods were shipped with.
  • order_number — the ShipperOne number of the sales order; sales_order_number — the order number in the sales channel.
  • replacement_order_id / replacement_order_number — the replacement order created for an exchange, if any.

Each returned item references the line it came from: fulfillment_order_item_id (the fulfillment order item id) and order_item_id (the sales order item id).

A return has two sides — what the customer sends back and, for an exchange, what is sent as replacement — and a balance between them. All amounts include tax.

FieldMeaning
return_shipping_amountShipping of the original order refunded with the return; 0 when the return does not include shipping.
return_grand_totalValue of the returned items, plus return_shipping_amount.
replacement_shipping_amountShipping charged on the replacement; 0 when none is charged.
replacement_grand_totalValue of the items sent as replacement, plus replacement_shipping_amount; 0 without a replacement.
settlement_totalreturn_grand_total − replacement_grand_total. Negative when the customer owes the difference — see Settlement type.

The value of the returned items alone is return_grand_total − return_shipping_amount; for the replacement, replacement_grand_total − replacement_shipping_amount.

These names differ from the fulfillment order and sales order amounts on purpose: a return has no single grand_total or shipping_amount, since each side carries its own.

Per item: qty, unit price and row_total, plus sku, erp_sku (the SKU as known to the ERP, when one is mapped), name, and a free-text description.

Once the credit memo is registered, the return carries creditmemo_number, creditmemo_time (when one was sent) and completed_at. Until then these fields are left out of the response.

Other fields: return_reason, total_qty, warehouse_code (the location the return is booked at), channel_code, the customer’s customer_firstname, customer_lastname, customer_email, and customer_name as entered on the return document.