Authenticate against the Returnly API using the merchant API key and retrieve the list of eligible order line items for return by querying the returns eligibility endpoint with the Shopify order ID
Create a return request via the Returnly returns POST endpoint, specifying return reason codes, quantities, and requested resolution type (refund, exchange, store credit)
Poll or webhook-subscribe to the Returnly return status endpoint to detect when a prepaid return label is generated, then surface the label URL to the customer
When Returnly marks the return as received (item inspected at warehouse), trigger the corresponding refund on the Shopify order using the Admin API refundCreate mutation to keep systems in sync
Handle exchange workflows by creating a new Shopify draft order for the replacement item and linking it to the Returnly return record via a custom attribute or note
Reconcile unresolved returns nightly by comparing open Returnly returns against Shopify refund records to catch any webhook failures
Known gotchas
Returnly and Shopify refund timing can diverge; issuing a Shopify refund before Returnly marks the item as received creates accounting discrepancies if the item is never returned
Returnly return eligibility windows and non-returnable item flags must be configured in the Returnly dashboard before the API will allow return creation for those items
Label generation may be asynchronous; do not assume a label URL is present immediately after return creation — poll status or rely on the webhook event
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