Returns (RMA)

Returns — also called RMA (Return Merchandise Authorization) — let a logged-in customer ask the store to take back or cancel an item they ordered. A customer can raise a return for an eligible item, converse with the store about it through a message thread, and cancel, reopen or close the request. Every return is scoped to the customer who owns it; a customer can only ever see and act on their own returns.

Authentication

All return endpoints require an authenticated customer — provide the storefront key and a customer Bearer token. See the Authentication page for how to obtain and send them.

How a return works

1. Find eligible items. Query returnableItems for an order to see which items are still within their return window and how many units can be returned or canceled.
2. Pick a reason. Query returnReasons for the resolution type (return or cancel_items) to get the reason ids to choose from.
3. Raise the return. Call createCustomerReturn with the order, the item, a quantity, the resolution type and a reason id. The return starts in a Pending status.
4. Converse. Read the thread with customerReturnMessages and add messages with createCustomerReturnMessage.
5. Cancel, reopen or close. Use cancelCustomerReturn, reopenCustomerReturn or closeCustomerReturn to change the state of the request.

Status flags

Each return carries three action flags that tell a client which operations are currently allowed:

Flag	Meaning
canClose	The return can be closed (marked solved) by the customer.
canReopen	The return can be reopened back to pending.
isExpired	The return is past its allowed action window.

These flags are populated on the single-return view; on the list they come back null.

Quantity caps are enforced by the store

When raising a return, the quantity you send is capped server-side by the trusted quantity a customer is actually allowed to return or cancel for that item (forReturnQuantity / forCancelQuantity from returnableItems). You can never return more units than were ordered and are still eligible.

Endpoints

Operation	GraphQL field	Description
List own returns	customerReturns	Paginated list of the customer's own returns.
View one return	customerReturn	A single return the customer owns.
List returnable items	returnableItems	Return-eligible items of one of the customer's orders.
List return reasons	returnReasons	Active reasons for a resolution type.
List return messages	customerReturnMessages	The conversation thread of a return.
Raise a return	createCustomerReturn	Create a new return for one order item.
Cancel a return	cancelCustomerReturn	Cancel the customer's own return.
Reopen a return	reopenCustomerReturn	Reopen a canceled/declined return.
Close a return	closeCustomerReturn	Mark a return solved.
Send a message	createCustomerReturnMessage	Add a message to the return conversation.