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).
| Endpoint | Purpose | ACL resource |
|---|---|---|
GET /V1/returns | List returns, 100 per page | Shipper_ShipmentReturn::api_returns_list |
GET /V1/returns/{incrementId} | Fetch one return by its number | Shipper_ShipmentReturn::api_returns_get |
GET /V1/returns/pending_creditmemo | List returns awaiting a credit memo | Shipper_ShipmentReturn::api_returns_pending_creditmemo |
POST /V1/return/creditmemo | Register the credit memo and complete a return | Shipper_ShipmentReturn::api_return_creditmemo |
List returns
Section titled “List returns”GET /rest/{store_code}/V1/returns?status=complete&page=1&date=2026-10-30%2000:00:00Authorization: Bearer <your-token>Accept: application/jsonQuery parameters — all optional, and combinable:
| Parameter | Description |
|---|---|
page | Page number, starting at 1. Page size is fixed at 100; iterate until you receive an empty array. |
date | yyyy-mm-dd hh:mm:ss — only returns updated at or after this time. |
channel | Sales channel code — only returns of orders from that channel. |
status | Only 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.
Fetch one return
Section titled “Fetch one return”GET /rest/{store_code}/V1/returns/R000000123Authorization: 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}.
Returns awaiting a credit memo
Section titled “Returns awaiting a credit memo”GET /rest/{store_code}/V1/returns/pending_creditmemo?page=1Authorization: Bearer <your-token>Accept: application/jsonLists 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.
Register the credit memo
Section titled “Register the credit memo”POST /rest/{store_code}/V1/return/creditmemoAuthorization: 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 returnidis 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 returnedqty.item_idis the return itemid. A missing, extra or repeated item, or a differentqty, returns 400.shipping_amount_incl_tax— required; the shipping of the original order refunded with the return, including tax. Use thereturn_shipping_amountreturned for the return; it is0when 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.
Statuses
Section titled “Statuses”| Status | Meaning |
|---|---|
draft | Being prepared in ShipperOne — not yet waiting for a credit memo. |
pending | Awaiting the credit memo — listed in pending_creditmemo. |
complete | Final — 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
Section titled “Settlement type”settlement_type tells which way the money goes, from the sign of settlement_total:
| Value | settlement_total | Meaning |
|---|---|---|
refund | positive | Money goes back to the customer. |
charge | negative | The customer pays the difference — the replacement is worth more than what was returned. |
none | zero | Nothing 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.
References
Section titled “References”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).
Amounts
Section titled “Amounts”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.
| Field | Meaning |
|---|---|
return_shipping_amount | Shipping of the original order refunded with the return; 0 when the return does not include shipping. |
return_grand_total | Value of the returned items, plus return_shipping_amount. |
replacement_shipping_amount | Shipping charged on the replacement; 0 when none is charged. |
replacement_grand_total | Value of the items sent as replacement, plus replacement_shipping_amount; 0 without a replacement. |
settlement_total | return_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.
Credit memo fields
Section titled “Credit memo fields”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.