Returns

Take return requests, approve or decline them, and complete them with a refund or an exchange.

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

GET read_orders

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.

Default: 25

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 400 INVALID_INPUT

    status, 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 return

GET read_orders

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.

Example: 4b1d9c1e-8a51-4b8e-9b61-0b3d2a6f7c10

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 404 RETURN_NOT_FOUND

    The return does not exist in this store.

Get return options

GET read_orders

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.

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.

Record a return

POST write_orders

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.

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

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.

Example: [{"order_item_id":"8f35b217-5ed7-4ad6-9ef4-4e2dced29ef6","quantity":1,"reason":"size_too_small","preference":"exchange","exchange_variant_id":54}]

Errors

  • 404 ORDER_NOT_FOUND

    The order does not exist in this store.

  • 400 RETURN_ITEMS_REQUIRED

    items is empty.

  • 400 RETURN_ITEM_NOT_RETURNABLE

    A 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.available is how many can be.

  • 400 RETURN_REASON_INVALID

    A reason is missing or not one of the listed values.

  • 400 RETURN_NOTE_TOO_LONG

    A note is too long.

  • 400 RETURN_EXCHANGE_ITEM_INVALID

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

  • 409 RETURNS_DISABLED

    Returns are turned off in Returns settings.

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

Approve a return

POST write_orders

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.

Example: 4b1d9c1e-8a51-4b8e-9b61-0b3d2a6f7c10

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 404 RETURN_NOT_FOUND

    The return does not exist in this store.

  • 409 RETURN_NOT_REQUESTED

    The return is not requested.

Decline a return

POST write_orders

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.

Example: 4b1d9c1e-8a51-4b8e-9b61-0b3d2a6f7c10

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.

Example: This item was marked final sale.

Errors

  • 404 RETURN_NOT_FOUND

    The return does not exist in this store.

  • 409 RETURN_NOT_REQUESTED

    The return is not requested.

  • 400 RETURN_DECLINE_REASON_REQUIRED

    reason is empty or longer than 500 characters.

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

Cancel a return

POST write_orders

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.

Example: 4b1d9c1e-8a51-4b8e-9b61-0b3d2a6f7c10

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 404 RETURN_NOT_FOUND

    The return does not exist in this store.

  • 409 RETURN_NOT_CANCELLABLE

    The return is closed, declined, cancelled, or its exchange credit was issued.

Mark a return received

POST write_orders

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.

Example: 4b1d9c1e-8a51-4b8e-9b61-0b3d2a6f7c10

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 404 RETURN_NOT_FOUND

    The return does not exist in this store.

  • 409 RETURN_NOT_RECEIVABLE

    The return isn't approved, or it was already completed.

Set a return's shipment

PUT write_orders

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.

Example: 4b1d9c1e-8a51-4b8e-9b61-0b3d2a6f7c10

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.

Example: in_transit
carrier string

Carrier name, at most 100 characters.

Example: Delhivery
tracking_number string

Tracking number, at most 100 characters.

Example: RT1234567890
tracking_url string

https tracking page, at most 2000 characters.

Example: https://www.delhivery.com/track/package/RT1234567890

Errors

  • 404 RETURN_NOT_FOUND

    The return does not exist in this store.

  • 400 RETURN_SHIPMENT_INVALID

    The status isn't one of the five, a value is too long, or the tracking URL isn't https.

  • 409 RETURN_SHIPMENT_CLOSED

    The return isn't approved: it is requested, declined, cancelled or completed.

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

Complete a return with a refund

POST write_orders

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.

Example: 4b1d9c1e-8a51-4b8e-9b61-0b3d2a6f7c10

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.

Example: original_payment
amount required string

The amount to refund, at most what the order can refund.

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

Example: [{"order_item_id":"8f35b217-5ed7-4ad6-9ef4-4e2dced29ef6","restock":true}]
notify_customer boolean

false keeps the refund email from being sent.

Example: true

Errors

  • 404 RETURN_NOT_FOUND

    The return does not exist in this store.

  • 409 RETURN_NOT_APPROVED

    The return is not approved.

  • 400 ORDER_REFUND_AMOUNT_POSITIVE

    amount is missing or not positive; every other Create a refund refusal applies too.

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

Complete a return with an exchange

POST write_orders

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.

Example: 4b1d9c1e-8a51-4b8e-9b61-0b3d2a6f7c10

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.

Example: [{"order_item_id":"8f35b217-5ed7-4ad6-9ef4-4e2dced29ef6","variant_id":54}]

Errors

  • 404 RETURN_NOT_FOUND

    The return does not exist in this store.

  • 409 RETURN_NOT_APPROVED

    The return is not approved.

  • 409 RETURN_EXCHANGE_UNAVAILABLE

    Exchanges are off, or the order has no customer account.

  • 400 RETURN_EXCHANGE_ITEM_INVALID

    A replacement is not another variant of the returned line's product, or of an active product when exchange_rules.products is any_product.

  • 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 return settings

GET read_orders

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

PUT write_orders

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.

Example: true
window_days integer

Days after delivery a customer can request a return, from limits.window_days_min to limits.window_days_max.

Example: 30
exchanges_enabled boolean

Customers can ask for another variant instead of a refund.

Example: true
instructions string

Where and how to send items back, emailed when a return is approved; at most limits.instructions_max_length characters.

Example: Pack the items and send them to 12 MG Road, Bengaluru 560001.
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.

Example: ["defective","wrong_item","size_too_small","size_too_large"]
note_required_reasons array<string>

Reasons for which a customer must add a note.

Example: ["defective","other"]
auto_refund_on_receipt boolean

Refund a return automatically once it is received, when every item asked for a refund.

Example: true
auto_refund_method string

Where automatic refunds go: original_payment or store_credit.

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

Example: [42]
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.

Example: {"enabled":true,"rules":[{"name":"Damaged items","reasons":["defective","wrong_item"],"max_order_value":"5000.00","max_days_since_delivery":14,"customer_group_ids":[]}]}
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.

Example: {"enabled":true,"first_after_days":7,"last_after_days":14,"expire_after_days":21}
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).

Example: {"enabled":true,"customer_group_ids":[],"protection":"pay_first","return_days":14}
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).

Example: {"products":"any_product","costs_more":"customer_pays","costs_less":"store_credit"}
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).

Example: {"wait":true,"other_variant":true,"refund":true,"answer_days":7,"default":"store_credit","wait_days":30}
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.

Example: {"enabled":true,"max_returns":3,"max_return_rate":40,"min_orders":3,"window_days":90,"action":"review","decline_reason":"","exempt_customer_group_ids":["0b8e2c1a-5f7d-4c3e-9a21-6d4f8b2e7c90"]}

Errors

  • 400 RETURN_SETTINGS_INVALID

    window_days is not 1 to 365, or instructions are longer than 2000 characters.

  • 400 RETURN_FINAL_SALE_TAGS_INVALID

    final_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.max is the limit.

  • 400 RETURN_REASONS_INVALID

    enabled_reasons is empty, or a reason isn't one of the list.

  • 400 RETURN_INSTANT_EXCHANGE_INVALID

    instant_exchange protection is not none or pay_first, return_days is outside 1 to 60, or a customer group isn't in this store.

  • 400 RETURN_EXCHANGE_FALLBACK_INVALID

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

  • 400 RETURN_REMINDERS_INVALID

    reminders days are not in order (first before last before expire) or are outside 1 to limits.reminder_days_max.

  • 400 RETURN_AUTO_APPROVE_INVALID

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

  • 400 RETURN_LIMITS_INVALID

    return_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.max is the group limit.

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