Raise a Return

About

The createCustomerReturn mutation raises a new return (RMA) request for one item of one of the customer's orders. The item must be return-eligible — check it with returnableItems first. The requested quantity (rmaQty) is capped server-side by the quantity the customer is actually allowed to return. The return starts in a Pending status.

Authentication

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

Input Fields

Field	Type	Required	Description
orderId	Int!	✅ Yes	Id of the order the item belongs to.
orderItemId	Int!	✅ Yes	Id of the order item being returned — from returnableItems.
rmaQty	Int!	✅ Yes	Quantity to return. Capped server-side by the returnable quantity.
resolutionType	String!	✅ Yes	return or cancel_items.
rmaReasonId	Int!	✅ Yes	Id of the chosen return reason — from returnReasons.
information	String	❌ No	Free-text note about the return.
packageCondition	String	❌ No	Reported package condition, e.g. opened.
agreement	Boolean!	✅ Yes	Must be true to confirm the return terms.

Possible Returns

Field	Type	Description
customerReturn._id	Int!	Numeric return ID.
customerReturn.orderId	Int!	Id of the order the item belongs to.
customerReturn.orderIncrementId	String!	Human-readable order number.
customerReturn.statusId	Int!	Numeric status id — 1 (Pending) for a fresh return.
customerReturn.statusTitle	String!	Status label.
customerReturn.statusColor	String!	Hex color for the status badge.
customerReturn.packageCondition	String	Reported package condition.
customerReturn.information	String	The note supplied when raising the return.
customerReturn.canClose	Boolean	Whether the return can be closed.
customerReturn.canReopen	Boolean	Whether the return can be reopened.
customerReturn.isExpired	Boolean	Whether the return is past its action window.
customerReturn.item	Object	The returned item — id, order_item_id, sku, name, quantity, resolution, reason_id, reason, variant_id. Query bare (a JSON object).
customerReturn.images	Array	Attached images (id, path, url). Empty on a JSON-created return. Query bare (a JSON array).
customerReturn.messagesCount	Int!	Number of conversation messages — 0 for a fresh return.
customerReturn.createdAt	DateTime!	Return creation timestamp.
customerReturn.updatedAt	DateTime!	Return last update timestamp.

Image attachments

Attaching image files to a return is available over REST only, via a multipart images[] field — files cannot be transported over a JSON GraphQL request.

Related Resources

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