Skip to main content

​
Authentication

All API requests require a Bearer token in the Authorization header: 
Authorization: Bearer YOUR_API_TOKEN

​
Getting Started

To use the Handled Returns API, you’ll need:
  1. Account ID - Your unique Handled account identifier
  2. API Token - Your secret authentication token

​
Request Headers

Include these headers with every API request: 
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json
Accept: application/json

​
Example Request

curl -X GET \
  https://your-domain.com/api/v1/accounts/123/returns \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json'

​
Token Security

  • Keep your API token secure and never expose it in client-side code
  • Rotate tokens regularly
  • Use environment variables to store tokens in your applications
  • Never commit tokens to version control

​
Rate Limiting

API requests are subject to rate limiting:
  • Returns endpoints: 1000 requests per hour
  • Storefront endpoints: 100 requests per minute per IP
  • Webhook endpoints: 10,000 requests per hour
Rate limit information is included in response headers:
  • X-RateLimit-Limit
  • X-RateLimit-Remaining
  • X-RateLimit-Reset

​
Error Responses

Failed authentication returns a 401 Unauthorized response: 
{
  "error": "Unauthorized",
  "error_code": "INVALID_TOKEN",
  "details": {
    "message": "Invalid or expired API token"
  }
}