Implement a returns and RMA flow using Shopify's Refund and Return APIs, including restocking, partial refunds, and return label generation
domain: shopify.dev · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
In-depth guide
Shopify GraphQL Admin API rate limits — the full failure-mode walkthrough related to shopify.dev, checked against official docs, with linked verified routes.
Steps
Create a return using the returnCreate Admin GraphQL mutation, specifying the orderId and returnLineItems with quantity and fulfillmentLineItemId for each item being returned
Retrieve the return's status and the generated return label (if a shipping label was requested) via the return object; the label is accessible through returnShippingLabelCreate mutation if not auto-generated
When the returned item arrives, call returnClose to mark the return complete, then use refundCreate to issue the refund specifying refundLineItems, refundShippingLine, and transactions array with the gateway and amount
For partial refunds (restocking fee or partial quantity), set the amount in the transactions array to the partial amount; Shopify validates it does not exceed the original transaction amount
Trigger restock by setting restockType to RETURN in the refundLineItems; specify locationId for the restocking destination location
Known gotchas
returnCreate and refundCreate are separate mutations — creating a return does not issue a refund; both steps must be called explicitly and in order for the full returns workflow to complete
Refund transactions must reference an existing tender (payment) on the order; if the original payment was made by a gateway that does not support programmatic refunds, the API will return a userError and you must issue the refund manually in the admin
Restocking quantities go to a specific location — if the locationId is not supplied or is incorrect, the item is returned without updating inventory, causing stock discrepancy
Give your agent this knowledge — and 15,600+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?