Raise a Return

Raise a new return (RMA) request for one item of one of the customer's orders. The item must be return-eligible — check it with GET /api/shop/returnable-items first. The requested quantity (rma_qty) is capped server-side by the quantity the customer is actually allowed to return. The return starts in a Pending status.

Endpoint

POST /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)

Request Body

{
  "order_id": 45,
  "order_item_id": 78,
  "rma_qty": 1,
  "resolution_type": "return",
  "rma_reason_id": 2,
  "information": "Item arrived damaged.",
  "package_condition": "opened",
  "agreement": true
}

Request Parameters

Parameter	Type	Required	Description
order_id	integer	Yes	Id of the order the item belongs to.
order_item_id	integer	Yes	Id of the order item being returned — from returnable-items.
rma_qty	integer	Yes	Quantity to return. Capped server-side by the returnable quantity.
resolution_type	string	Yes	return or cancel_items.
rma_reason_id	integer	Yes	Id of the chosen return reason — from return-reasons.
information	string	No	Free-text note about the return.
package_condition	string	No	Reported package condition, e.g. opened.
agreement	boolean	Yes	Must be true to confirm the return terms.

Image attachments

Optional image files can be attached to the return by sending the request as multipart/form-data with an images[] field alongside the fields above.

Response Fields (201 Created)

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 — 1 (Pending) for a fresh return.
statusTitle	string	Status label.
statusColor	string	Hex color for the status badge.
packageCondition	string	Reported package condition.
information	string	The note supplied when raising the return.
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 no files were sent.
messagesCount	integer	Number of conversation messages — 0 for a fresh return.
createdAt	string	ISO 8601 creation timestamp.
updatedAt	string	ISO 8601 last update timestamp.

Status Codes

Status	Meaning
201 Created	Return raised; status is Pending.
400 Bad Request	Item not eligible, invalid quantity, or agreement not true.
401 Unauthorized	Missing or invalid customer Bearer token.
403 Forbidden	Missing or invalid storefront key.
404 Not Found	The order does not exist or is not the customer's.

Related Resources

• List Returnable Items
• List Return Reasons
• Cancel a Return
• Returns Overview