API set up
Please refer to the guides to identify the integrations applicable to your use case.
API Endpoint Summary
| API | Purpose | Merchant Access | 3rd Party/Preferred Partner Access |
|---|---|---|---|
| Approve Return | Approve mail returns via API upon receipt and inspection | Self-service from the merchant dashboard settings page - see guide here | Reach out to Happy Returns to get initial API credentials or onboard new merchants |
| Get Return Details | Get current details of a return, or related returns | ||
| Get Outbound Shipment Details | Get comprehensive item details of an aggregated Happy Returns inbound shipment | ||
| Get NPS Details | Get high level or detailed NPS feedback | ||
| Get Nearby Locations | Get details of nearby Return Bars or Merchant Stores for a specific shopper | ||
| Create Headless Return | Start a Return Bar or in-store return (for headless returns integrations only) | For Headless Returns integrations only, reach out to Happy Returns for more information. | |
| Expire Headless Return | Manually expire a return (for headless returns integrations only) | ||
| Post Return Bag Contents | Send details about items in return polybags received from Happy Returns | ||
Authentication
Authentication to the Happy Returns API is done by simply adding an HTTP Header to each request. The Header name is always X-Hr-Apikey and the value for the header will be provided during integration for any applicable environments.
Rate Limiting
To ensure our platform remains stable and fair for everyone we rate limit the api using a leaky bucket algorithm. When API call occurs while the rate limit bucket is full the API responds with 429 Too Many Requests.
If your API call receives 429 Too Many Requests { ErrorMessage: “too many requests: limit 0.500000 requests/sec, leaky bucket size X” } then you should be able to make the request again after X seconds.
Currently the following partner apis are rate limited:
- RMA API is rate limited at partner and retailer level. If a partner has multiple retailers associated then partner has isolated bucket limit for each retailer.
- Return API and NPS API are rate limited at partner level. If a partner has multiple retailers associated then partner has combined bucket limit for all retailers.