List Returnable Items

List the items of one of the customer's orders that are still eligible for return — within their return window and not already fully returned or canceled. Each row carries the trusted quantity caps the store enforces when a return is raised (forReturnQuantity, forCancelQuantity, currentQuantity), so a client can present the correct maximum. Use these rows to pick the orderItemId and quantity for POST /api/shop/returns.

Endpoint

GET /api/shop/returnable-items

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
order_id	integer	Yes	Id of the order to list returnable items for. Must belong to the authenticated customer.

Response Fields (200 OK)

The response is a plain JSON array. Each item is a returnable-item object.

Field	Type	Description
orderItemId	integer	Id of the order item (order line) — send this as order_item_id when raising a return.
productId	integer	Id of the product.
sku	string	Product SKU.
name	string	Product name.
type	string	Product type, e.g. simple.
urlKey	string	Product URL key.
price	number	Item price.
baseImageUrl	string	URL of the product's base image.
qtyOrdered	integer	Quantity originally ordered.
currentQuantity	integer	Quantity currently eligible to act on.
forReturnQuantity	integer	Maximum units that can be returned.
forCancelQuantity	integer	Maximum units that can be canceled.
rmaQuantity	integer	Units already placed into a return.
rmaReturnPeriod	integer	Return window in days.

WARNING

orderItemId is the id of the order line, not of the product. Sending a productId as order_item_id when raising a return fails with The selected item is not eligible for return.

Units held by a canceled or declined return are released back into currentQuantity, so a shopper who withdrew a request can raise a new one for the same item.

Status Codes

Status	Meaning
200 OK	Returnable items retrieved.
401 Unauthorized	Missing or invalid storefront key.
403 Forbidden	Missing or invalid customer Bearer token.
404 Not Found	The order does not exist or is not the customer's.

Related Resources

• List Return Reasons — the reason ids to choose from
• List Return Custom Fields — the extra questions to answer in custom_attributes
• Raise a Return — raise a return against one order item
• Returns Overview — the returns menu overview, including the settings that gate it