Une API REST
sur laquelle vous appuyer.
Des endpoints authentifiés par clé Bearer et limités par scope couvrent les retours, le suivi et les étiquettes. Vous pouvez aussi interroger un agent de retours en français. Chaque clé a ses propres rate limits, et la plateforme programmable au sens large figure sur la roadmap.
Testez un appel.
Choisissez un endpoint. La requête et la réponse se mettent à jour à côté.
Récupérer un retour
Renvoie un retour au format JSON. {id} accepte le numéro de retour (RET-####) ou l’identifiant interne. Nécessite 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 }
]
}Tous les endpoints.
/api/v1/returns/{id} Récupérer un retour (JSON) · returns:read en ligne/api/v1/returns/{id}/tracking Statut de suivi en cours · returns:read en ligne/api/v1/returns/{id}/label PDF de l’étiquette de retour (redirection 302) · labels:read en ligne/api/v1/agent Agent de retours en langage naturel · returns:read en ligne/api/v1/openapi.json Spécification OpenAPI 3.1 · public en lignereturn.* Webhooks signés : created · approved · received · refunded · exchanged · cancelled en ligneComment les appels sont autorisés.
Clés Bearer
Envoyez Authorization: Bearer ret_live_<key> sur chaque appel /api/v1/*. La clé ne s’affiche qu’une seule fois, à sa création, et nous n’en conservons qu’une empreinte. Créez et révoquez vos clés dans Settings → API Keys.
Erreurs
- 401 clé inconnue ou révoquée
- 403 la clé n’a pas le scope requis
- 404 aucun retour de ce numéro dans votre boutique
- 429 rate limit dépassé (voir
Retry-After)
Chaque erreur renvoie un JSON { error, message, code }: error et message portent le même texte lisible ; code est un identifiant machine stable
(unauthorized, forbidden, not_found, rate_limited, …) sur lequel vous pouvez brancher sans risque.
Rate limits
120 requêtes par minute et par clé. Chaque réponse porte X-RateLimit-Limit, X-RateLimit-Remaining, et X-RateLimit-Reset ; en cas de 429 s’ajoute Retry-After.
Ce que l’API vous donne.
Roadmap des intégrations.
Shopify est disponible aujourd’hui. Dites-nous laquelle compte le plus pour votre stack et nous la prioriserons.
Commencez à construire avec Returner.
Créez une clé dans Settings → API Keys, puis lisez la spécification ou générez un client.