A returned shipment (RTO, return to origin) is recorded once for each shipment that reaches Returned, whoever reports it: a shipping app's tracking events or a status change. Reads use read_orders; every resolution uses write_orders.
payment says how the order was paid: cod (cash on delivery, nothing collected online), prepaid, or part_prepaid (cash on delivery with an online advance). A cod order whose shipments all came back with nothing left to ship is closed as undelivered at once: the order is cancelled (its shipments stay Returned), the pending cash payment is voided and the order leaves sales. Every other returned shipment is awaiting_decision until it is resolved; actions lists the resolutions open now.
Refund returns what the order can still give back for the shipment's items and, when nothing else of the order reached the customer, its charges (shipping too unless the store keeps it), to a destination the order can take (refund_methods on a single returned shipment). Reship reopens the shipment: its units count as unfulfilled and are held for the order again, and the fulfillment order's app gets fulfillment_orders/reopened to create a new fulfillment. Close undelivered cancels a cod or part_prepaid order whose shipments all came back, refunding an advance unless it is kept. Close resolves it without changing the order. Returned units go back on hand unless restock is false. Units that no location of the store stocks, such as dropshipped items, are refunded without going back on hand, and the returned shipment shows restocked false.
A prepaid shipment nobody decides on is refunded to the original payment once decision_hours pass when default_action is refund; one the order can't refund that way is left for the store. Each change fires rtos/created or rtos/resolved.
When the store has its Delivery portal on, the customer of a prepaid order can choose the same resolution there: Reship when the store allows it, or Refund to a destination the store allows; it is recorded as decided by the customer.
Before a shipment comes back, a failed delivery attempt opens a delivery issue for it, listed under GET /orders/{id}/delivery-issues. On the Delivery portal the customer asks for another attempt on a date they choose, correcting their phone, address lines and a note when the store allows it, or cancels the delivery. The answer fires delivery_issues/answered; the issue closes when the shipment moves on. The delivery portal settings (delivery_portal_enabled, delivery_answer_hours, delivery_allow_details, delivery_allow_cancel) are part of /rtos/settings.
Endpoints#
List returned shipments
List shipments that came back to the store undelivered, newest first.
An RTO (returned to origin) is recorded once for each shipment that reaches Returned, whoever reported it: a shipping app's tracking or staff. payment is cod (cash on delivery, nothing collected), prepaid, or part_prepaid (cash on delivery with an online advance). A cash-on-delivery order whose shipments all came back is closed as undelivered at once; every other RTO is awaiting_decision until it is refunded, sent again, closed as undelivered or closed. actions says which resolutions are open now. Filter by status, payment or order_id; counts.awaiting_decision is how many wait for a decision (up to 1000). Follow next_cursor while has_next is true; the cursor is bound to the filters.
Query parameters
| Name | Type | Description |
|---|---|---|
status
|
string |
Only returned shipments in this status.
Allowed values
awaiting_decisionresolved |
payment
|
string |
Only orders paid this way.
Allowed values
codprepaidpart_prepaid |
order_id
|
uuid |
Only this order's returned shipments. |
cursor
|
string |
next_cursor from the previous page, with the same filters. |
limit
|
integer |
Returned shipments per page, 1 to 100. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
400INVALID_INPUTstatus, payment, order_id or cursor is invalid.
-
400VALIDATION_LIST_INVALID_LIMITlimit is not between 1 and 100.
-
400STORE_API_QUERY_PARAMETER_UNKNOWNThe query string has a parameter this request does not accept. The message and
error.details.allowed_parameterslist the ones it does.
Get a returned shipment
Fetch one returned shipment with its items and the resolutions open now.
Path parameters
| Name | Type | Description |
|---|---|---|
id
required
|
uuid |
RTO id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
404RTO_NOT_FOUNDThe returned shipment does not exist in this store.
Refund a returned shipment
Refund what the customer paid for the shipment's items.
Refunds the shipment's items still refundable; when nothing else of the order reached the customer, the order's charges too, except shipping when Returned shipments settings keep it. The amount is what the order can still give back, priced as Create a refund prices it. Returned units go back on hand unless restock is false. Resolves the RTO in the refund's own transaction (rtos/resolved, plus the refund's events). The idempotency key is the RTO, so repeating the request after an uncertain response is safe. Not for cash-on-delivery orders with nothing collected: close those as undelivered.
Path parameters
| Name | Type | Description |
|---|---|---|
id
required
|
uuid |
RTO id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
method
|
string |
original_payment or store_credit. Omitted, Returned shipments settings decide (customer_choice refunds the original payment). |
restock
|
boolean |
Put the shipment's units back on hand. Omitted, the store's setting decides. |
Errors
-
404RTO_NOT_FOUNDThe returned shipment does not exist in this store.
-
409RTO_NOT_AWAITING_DECISIONThe returned shipment is already resolved.
-
409RTO_REFUND_UNAVAILABLENothing is left to refund.
-
400STORE_API_BODY_PROPERTY_UNKNOWNThe body has a property this request does not accept. The message and
error.details.propertieslist the allowed and required properties (nestedfor each object or list of objects). -
400STORE_API_BODY_PROPERTY_INVALIDA body property has the wrong type (
error.details.expected_type). The message anderror.details.propertieslist the allowed and required properties.
Send a returned shipment again
Send the shipment's units to the customer again.
The shipment keeps its Returned status and is marked reopened: its units count as unfulfilled again, are held for the order, and its fulfillment order is open for a new fulfillment. A fulfillment order assigned to an app is sent to it with fulfillment_orders/reopened. Refused when any of the units was refunded or the order was cancelled.
Path parameters
| Name | Type | Description |
|---|---|---|
id
required
|
uuid |
RTO id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
404RTO_NOT_FOUNDThe returned shipment does not exist in this store.
-
409RTO_NOT_AWAITING_DECISIONThe returned shipment is already resolved.
-
409RTO_RESHIP_UNAVAILABLEUnits were refunded, the shipment was already sent again, or the order was cancelled.
Close an order as undelivered
Cancel a cash-on-delivery order whose shipments all came back.
For cod and part_prepaid orders when every shipment that left came back and nothing is left to ship. The order is cancelled (its shipments stay Returned): it leaves sales, a pending cash-on-delivery payment is voided, and the customer gets the cancellation email. A part_prepaid advance is refunded to its payment unless keep_advance is true. Returned units go back on hand unless restock is false. Resolves every returned shipment of the order. A prepaid order is refunded instead.
Path parameters
| Name | Type | Description |
|---|---|---|
id
required
|
uuid |
RTO id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
restock
|
boolean |
Put the shipment's units back on hand. Omitted, the store's setting decides. |
keep_advance
|
boolean |
Keep a part_prepaid order's online advance instead of refunding it. |
Errors
-
404RTO_NOT_FOUNDThe returned shipment does not exist in this store.
-
409RTO_NOT_AWAITING_DECISIONThe returned shipment is already resolved.
-
409RTO_CLOSE_UNAVAILABLEThe order is prepaid, a shipment reached the customer, units are still to ship, or the order was cancelled.
-
400STORE_API_BODY_PROPERTY_UNKNOWNThe body has a property this request does not accept. The message and
error.details.propertieslist the allowed and required properties (nestedfor each object or list of objects). -
400STORE_API_BODY_PROPERTY_INVALIDA body property has the wrong type (
error.details.expected_type). The message anderror.details.propertieslist the allowed and required properties.
Close a returned shipment
Resolve a returned shipment without a refund or a new shipment.
For a shipment settled some other way. Nothing changes on the order; its units go back on hand unless restock is false.
Path parameters
| Name | Type | Description |
|---|---|---|
id
required
|
uuid |
RTO id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
restock
|
boolean |
Put the shipment's units back on hand. Omitted, the store's setting decides. |
Errors
-
404RTO_NOT_FOUNDThe returned shipment does not exist in this store.
-
409RTO_NOT_AWAITING_DECISIONThe returned shipment is already resolved.
-
400STORE_API_BODY_PROPERTY_UNKNOWNThe body has a property this request does not accept. The message and
error.details.propertieslist the allowed and required properties (nestedfor each object or list of objects). -
400STORE_API_BODY_PROPERTY_INVALIDA body property has the wrong type (
error.details.expected_type). The message anderror.details.propertieslist the allowed and required properties.
Get the RTO report
How many shipments came back undelivered in a period, by payment and by destination.
from_display and to_display are the period's days in the request language. Counts the shipments that left in the period (by the day they were created, in the store's time zone) and how many of them came back undelivered. rate is the returned share in percent, to one decimal place. by_payment splits them by how the order was paid (cod, part_prepaid, prepaid). by_region and by_postcode list the destinations with the most returned shipments, at most limits.top_places each; places with none returned are left out. Test orders are not counted. Without from or days, the 30 days ending on to; a period is at most limits.max_days days.
Query parameters
| Name | Type | Description |
|---|---|---|
from
|
date |
First day, YYYY-MM-DD in the store's time zone. |
to
|
date |
Last day, YYYY-MM-DD in the store's time zone. Defaults to today. |
days
|
integer |
Instead of |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
400INVALID_INPUTA date is not YYYY-MM-DD,
fromis afterto, or the period is longer thanlimits.max_daysdays. -
400STORE_API_QUERY_PARAMETER_UNKNOWNThe query string has a parameter this request does not accept. The message and
error.details.allowed_parameterslist the ones it does.
Get returned shipment settings
Read how returned shipments are handled.
decision_hours is how long a prepaid order's customer has to choose to have it sent again or refunded (from limits.decision_hours_min to limits.decision_hours_max). default_action applies when they don't: refund (a part_prepaid order is closed as undelivered with its advance refunded) or hold for the store. refund_method is where a refund goes: original_payment, store_credit or customer_choice. reship_enabled offers the customer sending it again. keep_shipping keeps the order's shipping charge out of a refund. restock puts returned units back on hand when a shipment is resolved. delivery_portal_enabled lets customers answer a failed delivery on the Delivery portal within delivery_answer_hours; delivery_allow_details and delivery_allow_cancel say whether they may correct their phone and address lines, and cancel. message_answers puts buttons on the Delivery Attempt Failed and Shipment Returned WhatsApp messages so the customer can answer in the chat.
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Update returned shipment settings
Change how returned shipments are handled.
Send the fields to change. A changed decision time applies to shipments that come back from now on.
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
decision_hours
|
integer |
Hours a prepaid order's customer has to choose, from limits.decision_hours_min to limits.decision_hours_max. |
default_action
|
string |
hold or refund. |
refund_method
|
string |
original_payment, store_credit or customer_choice. |
reship_enabled
|
boolean |
Offer the customer sending it again. |
keep_shipping
|
boolean |
Keep the order's shipping charge out of a refund. |
restock
|
boolean |
Put returned units back on hand when a shipment is resolved. |
delivery_portal_enabled
|
boolean |
Customers can answer a failed delivery on the Delivery portal (/delivery). |
delivery_answer_hours
|
integer |
Hours a customer has to answer a failed delivery, from limits.delivery_answer_hours_min to limits.delivery_answer_hours_max. |
delivery_allow_details
|
boolean |
Customers may correct their phone and address lines when they answer. |
delivery_allow_cancel
|
boolean |
Customers may cancel the delivery (the parcel comes back). |
message_answers
|
boolean |
The Delivery Attempt Failed and Shipment Returned WhatsApp messages carry buttons the customer can answer with, when the store's WhatsApp provider app shows them. |
Errors
-
400RTO_SETTINGS_INVALIDdecision_hours is out of range.
-
400INVALID_INPUTdefault_action or refund_method is not an allowed value.
-
400STORE_API_BODY_PROPERTY_UNKNOWNThe body has a property this request does not accept. The message and
error.details.propertieslist the allowed and required properties (nestedfor each object or list of objects). -
400STORE_API_BODY_PROPERTY_INVALIDA body property has the wrong type (
error.details.expected_type). The message anderror.details.propertieslist the allowed and required properties.
Answer a delivery problem for the customer
Record the customer's answer to a failed delivery attempt that they gave your app.
For a messaging, calling or support app that asked the customer itself. The answer is the customer's, exactly as if they had given it on the Delivery portal: the same choices and limits apply (Returned shipments settings decide whether they may correct details and cancel), the order's timeline says how they answered and through which app, and delivery_issues/answered is sent to the shipment's app. An answer can be changed while the shipment waits. Refused once the shipment moved on.
Path parameters
| Name | Type | Description |
|---|---|---|
id
required
|
uuid |
Order id. |
issueId
required
|
uuid |
Delivery problem id, from List an order's delivery problems or |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
choice
required
|
string |
reattempt or cancel. |
reattempt_on
|
string |
With reattempt: the day to deliver again, one of the next five days in the store's time zone (YYYY-MM-DD). |
phone
|
string |
A corrected phone number, when the store lets customers correct details. |
address1
|
string |
A corrected first address line. |
address2
|
string |
A corrected second address line. |
note
|
string |
A note for the courier, at most 500 characters. |
channel
required
|
string |
How the customer gave their answer: whatsapp, sms, phone, email, chat or other. It appears on the order's timeline. |
Errors
-
404DELIVERY_ISSUE_NOT_FOUNDThe order has no such delivery problem.
-
409DELIVERY_ISSUE_CLOSEDThe shipment moved on, or the order was cancelled.
-
409DELIVERY_PORTAL_DISABLEDThe store does not let customers answer failed deliveries.
-
400DELIVERY_DATE_INVALIDreattempt_onis not one of the next five days in the store's time zone. -
409RTO_CHOICE_UNAVAILABLEThe store does not let customers cancel a delivery.
-
400DELIVERY_ANSWER_TOO_LONGA note, address line or phone number is too long.
-
400STORE_API_BODY_PROPERTY_UNKNOWNThe body has a property this request does not accept. The message and
error.details.propertieslist the allowed and required properties (nestedfor each object or list of objects). -
400STORE_API_BODY_PROPERTY_INVALIDA body property has the wrong type (
error.details.expected_type). The message anderror.details.propertieslist the allowed and required properties.
Record the customer's choice for a returned shipment
Send it again or refund it, as the customer chose through your app.
For a messaging, calling or support app that asked the customer itself. The choice is the customer's, exactly as if they had made it on the Delivery portal: only what Returned shipments settings offer them is allowed (sending again when reship_enabled; a refund for a prepaid order, to method or, when the store decides, the store's refund method). The returned shipment is resolved as decided by the customer, and the order's timeline says how they answered and through which app.
Path parameters
| Name | Type | Description |
|---|---|---|
id
required
|
uuid |
RTO id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
choice
required
|
string |
reship or refund. |
method
|
string |
With refund, when the store lets customers choose: original_payment or store_credit. |
channel
required
|
string |
How the customer gave their answer: whatsapp, sms, phone, email, chat or other. It appears on the order's timeline. |
Errors
-
404RTO_NOT_FOUNDThe returned shipment does not exist in this store.
-
409RTO_NOT_AWAITING_DECISIONThe returned shipment is already resolved.
-
409RTO_CHOICE_UNAVAILABLEThe store does not offer this choice to customers, or
methodis not one the store refunds to. -
409DELIVERY_PORTAL_DISABLEDThe store does not let customers decide returned shipments.
-
400STORE_API_BODY_PROPERTY_UNKNOWNThe body has a property this request does not accept. The message and
error.details.propertieslist the allowed and required properties (nestedfor each object or list of objects). -
400STORE_API_BODY_PROPERTY_INVALIDA body property has the wrong type (
error.details.expected_type). The message anderror.details.propertieslist the allowed and required properties.
List an order's delivery problems
A failed delivery attempt and the customer's answer, per shipment.
One per shipment that reached a failed delivery attempt; a later failed attempt opens it again (attempts). status is open (waiting for the customer), answered or closed (the shipment moved on). choice is reattempt (on reattempt_on, a date in the store's time zone; reattempt_on_display is that day in the request language) or cancel; phone, address1 and address2 are corrections the customer made (null when unchanged) and note is for the courier. The answer is also sent as delivery_issues/answered.
Path parameters
| Name | Type | Description |
|---|---|---|
id
required
|
uuid |
Order id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
404ORDER_NOT_FOUNDThe order does not exist in this store.