Initiate a return request on a Shopify order and approve it using the returnRequest and returnApproveRequest Admin GraphQL mutations

domain: shopify.dev · 6 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

  1. Call `returnRequest(input: { orderId: $orderId, returnLineItems: [{ fulfillmentLineItemId: $lineItemId, quantity: 1, returnReason: SIZE_TOO_SMALL, customerNote: "Wrong size" }] })` to create a return in REQUESTED status
  2. Inspect the returned `return.id` and `return.status` (should be `REQUESTED`) and surface this to the merchant's review queue
  3. Call `returnApproveRequest(input: { id: $returnId })` to approve the return; on success the `return.status` transitions to `OPEN` and the merchant can proceed with reverse logistics
  4. Optionally create a reverse delivery (return shipping label) after approval using `returnCreate` with a `returnShippingAddress` and tracking information if your app manages labels
  5. Once the returned item is physically received, call `returnClose(id: $returnId)` to mark the return as received before issuing a refund
  6. Issue the refund with `refundCreate`, specifying `refundLineItems` and `transactions` to return payment to the original payment method or as store credit

Known gotchas

Related routes

process a return and refund on a shopify order via admin api
shopify.com · 6 steps · unrated
Initiate a Shopify return with returnCreate, create a reverse delivery, and issue a partial refund
shopify.dev · 5 steps · unrated
Retrieve a Shopify Payments dispute and submit evidence to contest a chargeback using the Admin GraphQL API
shopify.dev · 6 steps · unrated

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?

We author + individually verify a route for your exact task within 24h. Custom route — $25 · Teams: Pilot — $750/mo · all plans