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 — the orderItemId from returnableItems. This is the order line id, not the product id.
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 — open or packed. Any other value is rejected.
customAttributes	Iterable	⚠️ Conditional	Answers to the return form's custom fields, keyed by field id — see List Return Custom Fields. Required when the store has custom fields marked isRequired.
agreement	Boolean!	✅ Yes	Must be true to confirm the return terms.

Custom Fields

The store can configure additional questions the shopper answers while raising a return. Query them with returnCustomFields and send the answers in customAttributes, keyed by the field _id:

• every field with isRequired: true must be answered, otherwise the mutation is rejected
• select and radio answers must be one of the field's option values
• multiselect and checkbox answers take a list of option values
• the stored answers come back on the return as customAttributes

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). Always empty on a return raised through this mutation — see Attaching Evidence Photos. Query bare (a JSON array).
customerReturn.customAttributes	Array	Answers to the return's custom fields — field_id, code, label, type, value. Empty when the store has no custom fields. 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.

Attaching Evidence Photos

A binary part cannot travel in a JSON GraphQL request, and photos can only go in while the return is being raised — there is no endpoint that adds them afterwards. So when the shopper attached files, raise the whole return over REST instead of through this mutation, sending the same fields as multipart/form-data:

curl -X POST "https://your-store.com/api/shop/returns" \
  -H "X-STOREFRONT-KEY: pk_storefront_PvlE42nWGsKRVIf8bDlJngTPAdWAZbIy" \
  -H "Authorization: Bearer 438|aSV6JyFn299xuoR6wr5KKOodyIlMA26h0IgHiqLW" \
  -F "order_id=45" \
  -F "order_item_id=78" \
  -F "rma_qty=1" \
  -F "resolution_type=return" \
  -F "rma_reason_id=2" \
  -F "agreement=true" \
  -F "images[]=@/home/john/Pictures/damage-front.jpg" \
  -F "images[]=@/home/john/Pictures/damage-back.jpg"

Each file is checked against the mime types the store allows (Configuration → Sales → RMA → Allowed file extension). A return raised through this mutation always comes back with images empty, which is why the field reads as empty above rather than missing.

Files can still reach the store after the fact through the conversation — createCustomerReturnMessage documents the REST call that carries one file per message.

Related Resources

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