Returned shipments

Shipments that came back to the store undelivered (RTO), and how each is resolved: refund, send again, close as undelivered or close.

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

GET read_orders

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.

Default: 25

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 INVALID_INPUT

    status, payment, order_id or cursor is invalid.

  • 400 VALIDATION_LIST_INVALID_LIMIT

    limit is not between 1 and 100.

  • 400 STORE_API_QUERY_PARAMETER_UNKNOWN

    The query string has a parameter this request does not accept. The message and error.details.allowed_parameters list the ones it does.

Get a returned shipment

GET read_orders

Fetch one returned shipment with its items and the resolutions open now.

Path parameters

Name Type Description
id required uuid

RTO id.

Example: 6f0c2b8e-1d4a-4f6b-9a3e-2c7d8e9f0a1b

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 404 RTO_NOT_FOUND

    The returned shipment does not exist in this store.

Refund a returned shipment

POST write_orders

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.

Example: 6f0c2b8e-1d4a-4f6b-9a3e-2c7d8e9f0a1b

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).

Example: original_payment
restock boolean

Put the shipment's units back on hand. Omitted, the store's setting decides.

Example: true

Errors

  • 404 RTO_NOT_FOUND

    The returned shipment does not exist in this store.

  • 409 RTO_NOT_AWAITING_DECISION

    The returned shipment is already resolved.

  • 409 RTO_REFUND_UNAVAILABLE

    Nothing is left to refund.

  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).

  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

Send a returned shipment again

POST write_orders

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.

Example: 6f0c2b8e-1d4a-4f6b-9a3e-2c7d8e9f0a1b

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 404 RTO_NOT_FOUND

    The returned shipment does not exist in this store.

  • 409 RTO_NOT_AWAITING_DECISION

    The returned shipment is already resolved.

  • 409 RTO_RESHIP_UNAVAILABLE

    Units were refunded, the shipment was already sent again, or the order was cancelled.

Close an order as undelivered

POST write_orders

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.

Example: 6f0c2b8e-1d4a-4f6b-9a3e-2c7d8e9f0a1b

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.

Example: true
keep_advance boolean

Keep a part_prepaid order's online advance instead of refunding it.

Example: false

Errors

  • 404 RTO_NOT_FOUND

    The returned shipment does not exist in this store.

  • 409 RTO_NOT_AWAITING_DECISION

    The returned shipment is already resolved.

  • 409 RTO_CLOSE_UNAVAILABLE

    The order is prepaid, a shipment reached the customer, units are still to ship, or the order was cancelled.

  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).

  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

Close a returned shipment

POST write_orders

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.

Example: 6f0c2b8e-1d4a-4f6b-9a3e-2c7d8e9f0a1b

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.

Example: true

Errors

  • 404 RTO_NOT_FOUND

    The returned shipment does not exist in this store.

  • 409 RTO_NOT_AWAITING_DECISION

    The returned shipment is already resolved.

  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).

  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

Get the RTO report

GET read_orders

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.

Example: 2026-10-01
to date

Last day, YYYY-MM-DD in the store's time zone. Defaults to today.

Example: 2026-10-31
days integer

Instead of from: the period's length in days, ending on to, from 1 to limits.max_days.

Example: 90

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 INVALID_INPUT

    A date is not YYYY-MM-DD, from is after to, or the period is longer than limits.max_days days.

  • 400 STORE_API_QUERY_PARAMETER_UNKNOWN

    The query string has a parameter this request does not accept. The message and error.details.allowed_parameters list the ones it does.

Get returned shipment settings

GET read_orders

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

PUT write_orders

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.

Example: 72
default_action string

hold or refund.

Example: hold
refund_method string

original_payment, store_credit or customer_choice.

Example: customer_choice
reship_enabled boolean

Offer the customer sending it again.

Example: true
keep_shipping boolean

Keep the order's shipping charge out of a refund.

Example: false
restock boolean

Put returned units back on hand when a shipment is resolved.

Example: true
delivery_portal_enabled boolean

Customers can answer a failed delivery on the Delivery portal (/delivery).

Example: true
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.

Example: 48
delivery_allow_details boolean

Customers may correct their phone and address lines when they answer.

Example: true
delivery_allow_cancel boolean

Customers may cancel the delivery (the parcel comes back).

Example: true
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.

Example: true

Errors

  • 400 RTO_SETTINGS_INVALID

    decision_hours is out of range.

  • 400 INVALID_INPUT

    default_action or refund_method is not an allowed value.

  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).

  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

Answer a delivery problem for the customer

POST write_orders

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.

Example: da9b07a6-803f-4e41-8a18-97ff831bd588
issueId required uuid

Delivery problem id, from List an order's delivery problems or delivery_issues/opened.

Example: 1b0c6f2e-5a7d-4e3b-9c1f-2d8e7a6b5c4d

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
choice required string

reattempt or cancel.

Example: reattempt
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).

Example: 2026-11-09
phone string

A corrected phone number, when the store lets customers correct details.

Example: +919876543210
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.

Example: Call before coming
channel required string

How the customer gave their answer: whatsapp, sms, phone, email, chat or other. It appears on the order's timeline.

Example: phone

Errors

  • 404 DELIVERY_ISSUE_NOT_FOUND

    The order has no such delivery problem.

  • 409 DELIVERY_ISSUE_CLOSED

    The shipment moved on, or the order was cancelled.

  • 409 DELIVERY_PORTAL_DISABLED

    The store does not let customers answer failed deliveries.

  • 400 DELIVERY_DATE_INVALID

    reattempt_on is not one of the next five days in the store's time zone.

  • 409 RTO_CHOICE_UNAVAILABLE

    The store does not let customers cancel a delivery.

  • 400 DELIVERY_ANSWER_TOO_LONG

    A note, address line or phone number is too long.

  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).

  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

Record the customer's choice for a returned shipment

POST write_orders

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.

Example: 6f0c2b8e-1d4a-4f6b-9a3e-2c7d8e9f0a1b

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
choice required string

reship or refund.

Example: refund
method string

With refund, when the store lets customers choose: original_payment or store_credit.

Example: 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.

Example: phone

Errors

  • 404 RTO_NOT_FOUND

    The returned shipment does not exist in this store.

  • 409 RTO_NOT_AWAITING_DECISION

    The returned shipment is already resolved.

  • 409 RTO_CHOICE_UNAVAILABLE

    The store does not offer this choice to customers, or method is not one the store refunds to.

  • 409 DELIVERY_PORTAL_DISABLED

    The store does not let customers decide returned shipments.

  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).

  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

List an order's delivery problems

GET read_orders

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.

Example: da9b07a6-803f-4e41-8a18-97ff831bd588

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 404 ORDER_NOT_FOUND

    The order does not exist in this store.