A REST API
you can build on.
Bearer-key authenticated, scoped endpoints for returns, tracking, labels, and a natural-language returns agent — with per-key rate limits. The broader programmatic platform is on the roadmap.
Try a request.
Pick an endpoint — the request and response update beside it.
Get a return
Fetch a single return as JSON. {id} accepts the return number (RET-####) or the internal id. Requires returns:read.
curl https://app.returner.me/api/v1/returns/RET-9284 \
-H "Authorization: Bearer $RETURNER_API_KEY"{
"return_id": "RET-9284",
"order": "#1042",
"status": "in_transit",
"type": "refund",
"created_at": "2026-03-14T09:12:00Z",
"customer": { "name": "Maria Holm", "email": "[email protected]" },
"refund": { "amount": 49.00, "currency": "EUR" },
"carrier": "postnord",
"tracking_number": "SE392847561",
"items": [
{ "sku": "TEE-BLK-L", "name": "Cotton Tee",
"quantity": 1, "reason": "too_small", "condition": null }
]
}The endpoint ledger.
/api/v1/returns/{id} Get a return (JSON) · returns:read live/api/v1/returns/{id}/tracking Current tracking status · returns:read live/api/v1/returns/{id}/label Return label PDF (302 redirect) · labels:read live/api/v1/agent Natural-language returns agent · returns:read live/api/v1/openapi.json OpenAPI 3.1 spec · public livereturn.* · refund.* · exchange.* Outbound event subscriptions roadmapHow requests are authorized.
Bearer keys
Send Authorization: Bearer ret_live_<key> on every /api/v1/* request. Keys are shown once at creation — we store only a hash.
Generate and revoke keys in Settings → API Keys.
Errors
- 401 unknown or revoked key
- 403 key is missing the required scope
- 404 no such return in your store
- 429 rate limit exceeded (see
Retry-After)
Every error returns JSON { error, message, code } — error and message are the same human string; code is a stable
machine slug (unauthorized, forbidden, not_found, rate_limited, …) safe to branch on.
Rate limits
120 requests per minute per key. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset; 429s add Retry-After.
What the API gives you.
Integrations roadmap.
Shopify is live today. Tell us which is next for your stack and we'll prioritize it.
Start building with Returner.
Generate a key in Settings → API Keys, then read the spec or generate a client.