List Returns

Retrieve the authenticated customer's own return (RMA) requests, newest first. Requests are always scoped to the logged-in customer — a customer can never see another customer's returns. Every row carries the full return — the action flags (canClose, canReopen, isExpired), the images array and the customAttributes answers included — so a listing is enough to render the returns screen without a follow-up call per row.

Endpoint

GET /api/shop/returns

Authentication

This endpoint requires an authenticated customer — send the storefront key and a customer Bearer token. See the Authentication page.

Request Headers

Header	Required	Description
Content-Type	Yes	application/json
X-STOREFRONT-KEY	Yes	Your storefront API key
Authorization	Yes	Bearer token (customer login required)

Query Parameters

Parameter	Type	Required	Description
status	integer	No	Filter by return status id.

Response Fields (200 OK)

The response is a plain JSON array. Each item is a return object.

Field	Type	Description
id	integer	Return ID.
orderId	integer	Id of the order the item belongs to.
orderIncrementId	string	Human-readable order number.
statusId	integer	Numeric status id.
statusTitle	string	Status label, e.g. Pending.
statusColor	string	Hex color for the status badge.
packageCondition	string	Reported package condition — open or packed.
information	string	Free-text note supplied when the return was raised.
canClose	boolean	Whether the return can be closed.
canReopen	boolean	Whether the return can be reopened.
isExpired	boolean	Whether the return is past its action window.
item	object	The returned item — id, order_item_id, sku, name, quantity, resolution, reason_id, reason, variant_id.
images	array	Attached images (id, path, url). Empty when none were attached.
customAttributes	array	Answers to the return's custom fields — field_id, code, label, type, value. Empty when the store has no custom fields.
messagesCount	integer	Number of conversation messages on the return.
createdAt	string	ISO 8601 creation timestamp.
updatedAt	string	ISO 8601 last update timestamp.

Status Codes

Status	Meaning
200 OK	Returns retrieved.
401 Unauthorized	Missing or invalid storefront key.
403 Forbidden	Missing or invalid customer Bearer token.

Related Resources

• View Return — one return with its status flags
• Raise a Return — raise a return against one order item
• Returns Overview — the returns menu overview, including the settings that gate it