Obtain API credentials (X-Hr-Apikey) from your Happy Returns onboarding contact; pass the key as the X-Hr-Apikey HTTP header on every request to the Happy Returns API.
When a customer initiates a return in your portal, call the eligibility endpoint to check whether Happy Returns drop-off options (Return Bar, No Pack, No Pack or Print) are available for that order and item combination before displaying them.
If eligible, present the drop-off options to the customer; on selection, POST to the create-return endpoint with the order reference, selected items, reason codes, and the chosen drop-off method ID.
The API returns a QR code or label that the customer presents at the drop-off location (a Happy Returns Return Bar or participating retailer); no box or printing is required for the No Pack or Print option.
Subscribe to Happy Returns return status webhooks to receive events when the return is dropped off and when it reaches the consolidation hub; use these to trigger your refund or exchange flow.
For the newer Agentic Returns integration (MCP-based), use machine-to-machine OAuth2 client_credentials flow as documented in the agentic returns guide at developer.happyreturns.com.
Known gotchas
Eligibility must be checked per-item and per-order — blanket assumptions about drop-off availability based on geography alone will surface incorrect options to customers.
Refund timing depends on when Happy Returns processes the consolidated shipment at their hub, not when the customer drops off the package; set customer expectations accordingly.
The X-Hr-Apikey header grants access to all return operations for your merchant account; treat it as a secret and store it in a secrets manager, not in client-side code.
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