Call `returnRequest(input: { orderId: $orderId, returnLineItems: [{ fulfillmentLineItemId: $lineItemId, quantity: 1, returnReason: SIZE_TOO_SMALL, customerNote: "Wrong size" }] })` to create a return in REQUESTED status
Inspect the returned `return.id` and `return.status` (should be `REQUESTED`) and surface this to the merchant's review queue
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
Optionally create a reverse delivery (return shipping label) after approval using `returnCreate` with a `returnShippingAddress` and tracking information if your app manages labels
Once the returned item is physically received, call `returnClose(id: $returnId)` to mark the return as received before issuing a refund
Issue the refund with `refundCreate`, specifying `refundLineItems` and `transactions` to return payment to the original payment method or as store credit
Known gotchas
returnRequest requires the `write_returns` access scope; apps without this scope will receive an access denied error even if they have write_orders
A returnRequest can only be made on orders where at least one fulfillment exists in a fulfilled state — requesting a return on an unfulfilled or cancelled order returns a validation error
Approving a return (returnApproveRequest) does not automatically generate a return shipping label or initiate a refund — these are separate steps requiring additional mutations or third-party label provider integration
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp