Generate an API key in the Loop admin under Returns Management > Tools & Integrations > Developer Tools; assign the Return and Developer Tools scopes required for returns reads and webhook management.
Include the key in every request as the X-Authorization HTTP header; Loop's API base URL is documented at docs.loopreturns.com.
Retrieve a return record by calling the Returns API with the order ID or return ID; the response includes line items, customer-selected outcomes (exchange, store credit, refund), and current return status.
Subscribe to return lifecycle webhooks (return.created, return.label_created, return.closed, return.refunded, return.exchange_created) by registering your endpoint URL via the Programmatic Webhooks API — this endpoint requires the Developer Tools scope.
When a return.closed webhook arrives, inspect the resolution field to determine whether to trigger a refund, issue store credit, or create a replacement order in your OMS.
Use the Process Return endpoint to manually trigger outcome execution for returns flagged as needing review, and the Flag Return endpoint to escalate edge cases to the Loop admin queue.
Known gotchas
API keys are shop-specific and scope-enforced — a key without the Return scope will receive 401 Unauthorized on returns endpoints even if authentication succeeds.
Loop webhooks do not include a cryptographic signature by default; validate the source IP range or implement a shared secret if your endpoint must be publicly accessible.
The Loop API operates on Shopify-backed data; order IDs must match Shopify order IDs — using your internal OMS order numbers will cause lookups to return empty results.
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