Call the `returnCreate` mutation with the `orderId` and a `returnLineItems` array specifying `fulfillmentLineItemId`, `quantity`, and `returnReason` for each item being returned.
Once the return is created, use `reverseDeliveryCreateWithShipping` or mark the return as received using `returnReceive` after the physical goods arrive, updating return line item statuses.
To issue a refund for the returned items, call the `refundCreate` mutation with `orderId`, `refundLineItems` (referencing `lineItemId` and quantity), and `transactions` specifying the refund amount and `gateway`.
Set `shipping` in the refund input if you also want to refund shipping costs, and set `notify` to true to email the customer.
Check `refundCreate` response for `userErrors` and validate that the returned `refund.transactions` reflect the expected amounts.
For restocking returned inventory, ensure `restockType` is set to `RETURN` or `CANCEL` in the refund line items input, and verify the target location is specified.
Known gotchas
Refunds are distinct from returns in the data model — creating a return does not automatically issue a refund; you must call `refundCreate` separately.
You can only refund up to the original payment amount per transaction; attempting to exceed this returns a user error about maximum refundable amount.
For orders paid with multiple payment methods or split transactions, each transaction must be refunded individually against its own `transactionId`.
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