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. The detail-only action flags (canClose, canReopen, isExpired) and the images array come back null on the listing — fetch a single return to get them.

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, e.g. opened.
information	string	Free-text note supplied when the return was raised.
canClose	boolean	Whether the return can be closed. null on the listing.
canReopen	boolean	Whether the return can be reopened. null on the listing.
isExpired	boolean	Whether the return is past its action window. null on the listing.
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). null on the listing.
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 customer Bearer token.
403 Forbidden	Missing or invalid storefront key.

Related Resources

• View Return
• Raise a Return
• Returns Overview