A return covers delivered items a customer sends back. Customers request one on the store's Returns portal (/returns) when returns are turned on in Returns settings; you can also record one yourself. Reads use read_orders; every change uses write_orders.
A return moves through requested, then approved or declined, then closed once it is completed with a refund or an exchange. A requested or approved return can be cancelled. Only delivered units can be returned, within the store's window counted from delivery, and never units that were refunded, are still waiting to ship, or are already in an open return. Gift Cards cannot be returned.
The customer is emailed when you approve a return (with the instructions from Returns settings) or decline it (with your reason). Complete with a refund to create one refund for exactly the return's items. Complete with an exchange to refund their value to the customer's Store Credit and create an exchange order for other variants of the same products, paid from that credit. Each returned item is restocked unless you turn restocking off for it.
Every change fires a returns/* webhook, and the order's own response lists its returns.
Endpoints#
List returns
List the store's returns, newest first.
Returns the store's returns in (created_at, id) order, newest first, with their items. Filter by status (requested, approved, declined, closed, cancelled, expired) or order_id. status_display, outcome_display and each item's reason_display are worded in the request language. Follow next_cursor while has_next is true; the cursor is bound to the filters.
Query parameters
| Name | Type | Description |
|---|---|---|
status
|
string |
Only returns in this status.
Allowed values
requestedapproveddeclinedclosedcancelledexpired |
order_id
|
uuid |
Only this order's returns. |
cursor
|
string |
next_cursor from the previous page, with the same filters. |
limit
|
integer |
Returns per page, 1 to 100. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
400INVALID_INPUTstatus, 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 return
Fetch one return with its items.
The order's own GET /orders/{id} lists its returns too. photos are the photos the customer added when asking for the return (at most 6, stored as JPEG without location data). Their url is a signed link that works for expires_in seconds: read the return again for fresh links. Photos are kept until 90 days after the return closes and are deleted with the order. limit_flag is set when the customer's request went over one of the store's return limits: kind count or rate, value against limit over window_days, action review (held for you) or decline (declined automatically), and message, worded in the request language; it is null otherwise. auto_approved_rule names the auto-approve rule that approved the customer's request at once (null when a person approved it, or it isn't approved). expires_at is when an approved return the customer hasn't sent back expires, with return reminders on (null otherwise); an expired return has status expired and its items can be returned again while the window allows. exchange_hold is set while an exchange waits because a replacement is out of stock: awaiting_choice (the customer chooses on the Returns portal what to do instead) or waiting_restock (the exchange goes ahead as soon as the item is back), until exchange_hold_until; null otherwise.
Path parameters
| Name | Type | Description |
|---|---|---|
id
required
|
uuid |
Return id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
404RETURN_NOT_FOUNDThe return does not exist in this store.
Get return options
What can be returned from an order, line by line.
lines lists each line that has something returnable: returnable_quantity is the delivered units not refunded and not in an open return, and return_by is when the store's return window for it ends (within_window false once it has passed; a merchant can still record the return, a customer can't). final_sale is true when the product carries one of the store's final-sale tags: a customer can't return it, a merchant can still record the return. A line is returnable only once all of it has shipped, and never for Gift Cards or lines that don't ship. exchange_available says whether an exchange is possible: exchanges are on in Returns settings and the order has a customer account. reasons lists the reasons with their labels.
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.
Record a return
Record a return for an order, already approved.
For a return the customer arranged with you some other way. It is created approved, so it goes straight to Complete (refund or exchange); the window is not applied, but every other rule of return-options is. Fires returns/requested and returns/approved. The customer is not emailed.
Path parameters
| Name | Type | Description |
|---|---|---|
id
required
|
uuid |
Order id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
items
required
|
array<object> |
One object per line: order_item_id, quantity, reason (size_too_small, size_too_large, not_as_described, defective, wrong_item, changed_mind or other), optional note (at most 500 characters), preference (refund or exchange, default refund) and, for an exchange, exchange_variant_id (another variant of the same product) or, when exchange_rules.products is any_product, exchange_product_id for another active product, with exchange_variant_id when that product has variants. |
Errors
-
404ORDER_NOT_FOUNDThe order does not exist in this store.
-
400RETURN_ITEMS_REQUIREDitems is empty.
-
400RETURN_ITEM_NOT_RETURNABLEA line can't be returned in that quantity: it isn't delivered, part of it is still waiting to ship, it was refunded, it is already in an open return, or it is a Gift Card or a line that doesn't ship.
details.availableis how many can be. -
400RETURN_REASON_INVALIDA reason is missing or not one of the listed values.
-
400RETURN_NOTE_TOO_LONGA note is too long.
-
400RETURN_EXCHANGE_ITEM_INVALIDThe replacement is not another variant of the same product or, with exchange_rules.products any_product, a variant or simple product of another active product.
-
409RETURNS_DISABLEDReturns are turned off in Returns settings.
-
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.
Approve a return
Approve a requested return.
The customer is emailed the return instructions from Returns settings. Fires returns/approved.
Path parameters
| Name | Type | Description |
|---|---|---|
id
required
|
uuid |
Return id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
404RETURN_NOT_FOUNDThe return does not exist in this store.
-
409RETURN_NOT_REQUESTEDThe return is not requested.
Decline a return
Decline a requested return with a reason.
The customer is emailed the reason. Fires returns/declined. The items can be requested again.
Path parameters
| Name | Type | Description |
|---|---|---|
id
required
|
uuid |
Return id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
reason
required
|
string |
What the customer is told, at most 500 characters. |
Errors
-
404RETURN_NOT_FOUNDThe return does not exist in this store.
-
409RETURN_NOT_REQUESTEDThe return is not requested.
-
400RETURN_DECLINE_REASON_REQUIREDreason is empty or longer than 500 characters.
-
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.
Cancel a return
Cancel a requested or approved return.
A return that is completed or declined can't be cancelled. An exchange whose credit was already issued can't be cancelled either: it completes when the credit lands. Fires returns/cancelled.
Path parameters
| Name | Type | Description |
|---|---|---|
id
required
|
uuid |
Return id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
404RETURN_NOT_FOUNDThe return does not exist in this store.
-
409RETURN_NOT_CANCELLABLEThe return is closed, declined, cancelled, or its exchange credit was issued.
Mark a return received
Record that an approved return's items reached the store.
Sets received_at and fires returns/received. Marking it again changes nothing. When the store refunds automatically on receipt (auto_refund_on_receipt in return settings) and every item asked for a refund, the return is then refunded to auto_refund_method and completed (returns/closed); a refund that can't be made is written on the order for staff and the return stays received.
Path parameters
| Name | Type | Description |
|---|---|---|
id
required
|
uuid |
Return id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Errors
-
404RETURN_NOT_FOUNDThe return does not exist in this store.
-
409RETURN_NOT_RECEIVABLEThe return isn't approved, or it was already completed.
Set a return's shipment
Record or update an approved return's shipment back to the store.
For any shipping app, or staff, that books the return pickup. Send the whole shipment each time; one per return. status is label_created, in_transit, delivered, failed or cancelled. Every change fires returns/shipment_updated. delivered also marks the return received, as Mark a return received does. The customer sees the tracking on the Returns portal.
Path parameters
| Name | Type | Description |
|---|---|---|
id
required
|
uuid |
Return id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
status
required
|
string |
label_created, in_transit, delivered, failed or cancelled. |
carrier
|
string |
Carrier name, at most 100 characters. |
tracking_number
|
string |
Tracking number, at most 100 characters. |
tracking_url
|
string |
https tracking page, at most 2000 characters. |
Errors
-
404RETURN_NOT_FOUNDThe return does not exist in this store.
-
400RETURN_SHIPMENT_INVALIDThe status isn't one of the five, a value is too long, or the tracking URL isn't https.
-
409RETURN_SHIPMENT_CLOSEDThe return isn't approved: it is requested, declined, cancelled or completed.
-
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.
Complete a return with a refund
Refund an approved return's items and complete it.
Creates one refund for exactly the return's items, the same way Create a refund does (method, amount, payment, notification), and completes the return in the same step (returns/closed, plus the refund's own events). Each item is restocked unless you send restock: false for it; restock_location_id picks where. The refund's idempotency key is the return, so repeating the request after an uncertain response is safe.
Path parameters
| Name | Type | Description |
|---|---|---|
id
required
|
uuid |
Return id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
method
required
|
string |
original_payment, store_credit or manual, as in Create a refund. |
amount
required
|
string |
The amount to refund, at most what the order can refund. |
payment_id
|
uuid |
The payment to refund, for original_payment. |
items
|
array<object> |
Restock choices by line: order_item_id, restock (default true) and optional restock_location_id. |
notify_customer
|
boolean |
false keeps the refund email from being sent. |
Errors
-
404RETURN_NOT_FOUNDThe return does not exist in this store.
-
409RETURN_NOT_APPROVEDThe return is not approved.
-
400ORDER_REFUND_AMOUNT_POSITIVEamount is missing or not positive; every other Create a refund refusal applies too.
-
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.
Complete a return with an exchange
Exchange an approved return's items for other variants of the same products.
Refunds the returned items' value to the customer's Store Credit (restocking each unless restock: false), then creates an exchange order for the replacements, paid from that credit, with free shipping and the order confirmation email. If the replacements cost more, the exchange order is left with the difference to pay: the customer is sent a payment link when the order's market has online payment, otherwise it is collected on delivery when cash on delivery is available for the address (its usual fee applies); with neither, the exchange is refused with RETURN_EXCHANGE_PAYMENT_UNAVAILABLE. If they cost less, exchange_rules.costs_less decides where the difference goes: it stays in Store Credit, is refunded to the original payment (Store Credit when that payment can't take a refund), or the store keeps it. With exchange_rules.products any_product, a replacement can be a variant of any active product. When a replacement is out of stock nothing is refunded yet: the return stays approved with exchange_hold awaiting_choice and the customer is sent the Exchange Item Unavailable email to choose, on the Returns portal, among the options in the exchange_fallback settings (wait for restock, another in-stock option, Store Credit, or a refund to the original payment). With no choice by exchange_hold_until the store's default applies; a wait that runs out ends in Store Credit. You can still refund the return yourself while it waits. The exchange order carries the exchange tag; Reports count its items as sold but not as a new order, and it is not sent to ad apps as a purchase. The Store Credit is added in the background: the response may still show the return approved with its refund_id, and it completes (returns/closed, exchange_order_id) as soon as the credit lands. Needs exchanges on in Returns settings and a customer account on the order.
Path parameters
| Name | Type | Description |
|---|---|---|
id
required
|
uuid |
Return id. |
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
items
required
|
array<object> |
One object per returned line: order_item_id, optional variant_id (another variant of the same product, replacing the one the return asked for; omitted, the return's own exchange_variant_id or exchange_product_id is used), restock (default true) and optional restock_location_id. |
Errors
-
404RETURN_NOT_FOUNDThe return does not exist in this store.
-
409RETURN_NOT_APPROVEDThe return is not approved.
-
409RETURN_EXCHANGE_UNAVAILABLEExchanges are off, or the order has no customer account.
-
400RETURN_EXCHANGE_ITEM_INVALIDA replacement is not another variant of the returned line's product, or of an active product when exchange_rules.products is any_product.
-
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 return settings
Read whether customers can request returns, and the rules. With `auto_approve` enabled, a customer's request that passes the return limits is approved at once by the first of `rules`, in order, whose conditions all hold: every item's reason in `reasons` (empty: any), the order total at most `max_order_value` (store currency), every item delivered at most `max_days_since_delivery` days ago, and the customer in one of `customer_group_ids` (empty: anyone; guest orders never match a rule that names groups). The customer gets the Return Approved email and the return's `auto_approved_rule` names the rule; nothing matching leaves the request for you. With `reminders` enabled, a return the customer asked for that is approved but not sent back gets a Return Reminder `first_after_days` after approval and a last one `last_after_days` after approval; at `expire_after_days` it closes as expired (`returns/expired`, Return Expired email). Any recorded or tracked return shipment, or receiving the return, stops the reminders. Returns you record yourself never get reminders. `exchange_fallback` decides what happens when an exchange's replacement is out of stock: the customer may choose among Store Credit and the options turned on (`wait`, `other_variant`, `refund`) for `answer_days`, after which `default` applies; a wait for restock lasts up to `wait_days` and then ends in Store Credit. `exchange_rules` decide which replacements customers may choose (`products`: same_product or any_product) and what happens to a price difference: `costs_more` customer_pays (the exchange order carries the difference) or not_offered (a customer's request whose replacement costs more is refused with RETURN_EXCHANGE_COSTS_MORE), and `costs_less` store_credit, original_payment or store_keeps. With `instant_exchange` enabled, an approved exchange the customer asked for (every item an exchange, a customer account and, when `customer_group_ids` are set, in one of those groups) ships its replacement at once, before the items come back: with `protection` none the exchange credit is issued and pays the exchange order straight away, and the return completes when the items are received; with pay_first the customer pays for the replacement on the exchange order and the returned items are refunded to the original payment when received. The items are due within `return_days` (the return's `instant_due_at`): a none exchange that passes it is flagged to you on the order, a pay_first one expires with no refund. Returned items go back into stock when received.
enabled lets customers request returns on the store's Returns portal (/returns). window_days counts from delivery. warnings lists, in the request language, where the settings fall short of a law the store's customers have; today one: RETURN_WINDOW_BELOW_EU_MINIMUM, when returns are on with a window under 14 days and an active market sells to an EU country. Warnings never block a save: merchants comply themselves. instructions is emailed when a return is approved. enabled_reasons are the reasons customers can choose, and a reason in note_required_reasons needs a note from them. With auto_refund_on_receipt, a return whose items all asked for a refund is refunded to auto_refund_method once it is received. Products carrying one of final_sale_tag_ids (product tags; final_sale_tags names them) are final sale: customers can't return them on the Returns portal, but staff can still record a return. return_limits holds requests from customers who return a lot: with enabled, a request that would make more than max_returns returns in the last window_days, or return more than max_return_rate percent of what the customer bought in that time (counted once they have at least min_orders orders in that time), is held for review or, with action decline, declined automatically with decline_reason. Customers in exempt_customer_group_ids (exempt_customer_groups names them) are never limited; guest orders without a customer account aren't either. Requests you record yourself skip the limits. A second warning, RETURN_LIMIT_DECLINE_EU, appears when requests over a limit are declined automatically and an active market sells to an EU country. limits are the bounds the API enforces, final_sale_tags_max among them: the window in days (window_days_min, window_days_max) and the longest instructions, customer note and decline reason, in characters.
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Update return settings
Change the return rules.
Send the fields to change. Turning returns off stops new customer requests; returns already open carry on.
Headers
| Name | Type | Description |
|---|---|---|
Authorization
required
|
string |
Bearer Store API token. |
Body parameters
| Name | Type | Description |
|---|---|---|
enabled
|
boolean |
Customers can request returns on the store's Returns portal. |
window_days
|
integer |
Days after delivery a customer can request a return, from limits.window_days_min to limits.window_days_max. |
exchanges_enabled
|
boolean |
Customers can ask for another variant instead of a refund. |
instructions
|
string |
Where and how to send items back, emailed when a return is approved; at most limits.instructions_max_length characters. |
enabled_reasons
|
array<string> |
Reasons customers can choose on the Returns portal: size_too_small, size_too_large, not_as_described, defective, wrong_item, changed_mind, other. At least one. |
note_required_reasons
|
array<string> |
Reasons for which a customer must add a note. |
auto_refund_on_receipt
|
boolean |
Refund a return automatically once it is received, when every item asked for a refund. |
auto_refund_method
|
string |
Where automatic refunds go: original_payment or store_credit. |
final_sale_tag_ids
|
array<integer> |
Product tags whose products are final sale: customers can't return them on the Returns portal. Replaces the list; at most limits.final_sale_tags_max. |
auto_approve
|
object |
Auto-approve rules, sent whole: enabled and rules, in order. Each rule has a name and optional conditions: reasons (every requested item's reason is one of them; empty for any), max_order_value (order total in the store's currency), max_days_since_delivery (every item delivered at most this many days ago) and customer_group_ids (the customer is in one of them; empty for anyone). Bounds are in limits. |
reminders
|
object |
Return reminders, sent whole: enabled, first_after_days, last_after_days and expire_after_days, counted from approval; each later than the one before, at most limits.reminder_days_max. |
instant_exchange
|
object |
Instant exchange, sent whole: enabled, customer_group_ids (empty for every customer with an account), protection (none or pay_first) and return_days (1 to 60). |
exchange_rules
|
object |
Exchange rules, sent whole: products (same_product or any_product), costs_more (customer_pays or not_offered) and costs_less (store_credit, original_payment or store_keeps). |
exchange_fallback
|
object |
What happens when an exchange's replacement is out of stock, sent whole: wait, other_variant and refund (options the customer may choose besides Store Credit), answer_days (time to choose), default (store_credit, refund or wait; applied when the customer doesn't choose) and wait_days (longest wait for restock, then Store Credit). |
return_limits
|
object |
Return limits, sent whole: enabled, max_returns (null for no count limit), max_return_rate (percent, null for no rate limit), min_orders, window_days, action (review or decline), decline_reason (needed for decline, at most limits.decline_reason_max_length characters) and exempt_customer_group_ids. Bounds are in limits. |
Errors
-
400RETURN_SETTINGS_INVALIDwindow_days is not 1 to 365, or instructions are longer than 2000 characters.
-
400RETURN_FINAL_SALE_TAGS_INVALIDfinal_sale_tag_ids has more than limits.final_sale_tags_max tags, or a tag that isn't one of the store's product tags.
details.maxis the limit. -
400RETURN_REASONS_INVALIDenabled_reasons is empty, or a reason isn't one of the list.
-
400RETURN_INSTANT_EXCHANGE_INVALIDinstant_exchange protection is not none or pay_first, return_days is outside 1 to 60, or a customer group isn't in this store.
-
400RETURN_EXCHANGE_FALLBACK_INVALIDexchange_fallback answer_days or wait_days are outside 1 to limits.exchange_answer_days_max / limits.exchange_wait_days_max, or default is an option that's off.
-
400RETURN_REMINDERS_INVALIDreminders days are not in order (first before last before expire) or are outside 1 to limits.reminder_days_max.
-
400RETURN_AUTO_APPROVE_INVALIDauto_approve has more than limits.auto_approve_rules_max rules, a rule without a name or with one longer than limits.auto_approve_name_max_length, a reason that isn't one of the list, more than limits.auto_approve_groups_max groups or a group that isn't the store's, or a max_order_value or max_days_since_delivery outside its bounds.
-
400RETURN_LIMITS_INVALIDreturn_limits is enabled with neither max_returns nor max_return_rate, a value is outside its bounds in limits, exempt_customer_group_ids has more than limits.return_limit_exempt_groups_max groups or a group that isn't the store's, or action is decline without a decline_reason.
details.maxis the group limit. -
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.