Un’API REST
su cui puoi costruire.
Endpoint con autenticazione Bearer e scope per resi, tracking, etichette e un agente dei resi a cui puoi chiedere in italiano, con rate limit per key. La piattaforma programmabile più ampia è sulla roadmap.
Prova una request.
Scegli un endpoint. Request e response si aggiornano qui accanto.
Leggere un reso
Restituisce un singolo reso in JSON. {id} accetta il numero del reso (RET-####) oppure l’id interno. Richiede 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 }
]
}L’elenco degli endpoint.
/api/v1/returns/{id} Leggere un reso (JSON) · returns:read attivo/api/v1/returns/{id}/tracking Stato del tracking · returns:read attivo/api/v1/returns/{id}/label PDF dell’etichetta di reso (redirect 302) · labels:read attivo/api/v1/agent Agente dei resi in linguaggio naturale · returns:read attivo/api/v1/openapi.json Specifica OpenAPI 3.1 · pubblica attivoreturn.* Webhook firmati: created · approved · received · refunded · exchanged · cancelled attivoCome vengono autorizzate le request.
Bearer key
Invia Authorization: Bearer ret_live_<key> a ogni /api/v1/*. La key viene mostrata una volta sola alla creazione e noi ne conserviamo solo un hash. Le key si creano e si revocano in Settings → API Keys.
Errori
- 401 key sconosciuta o revocata
- 403 alla key manca lo scope richiesto
- 404 nessun reso con questo id nel tuo negozio
- 429 rate limit superato (vedi
Retry-After)
Ogni errore risponde in JSON { error, message, code }: error e message sono la stessa stringa leggibile; code è uno slug stabile per le macchine
(unauthorized, forbidden, not_found, rate_limited, …) su cui puoi ramificare in sicurezza.
Rate limit
120 request al minuto per key. Ogni response porta X-RateLimit-Limit, X-RateLimit-Remaining, e X-RateLimit-Reset; con un 429 si aggiunge Retry-After.
Che cosa ti dà l’API.
Roadmap delle integrazioni.
Shopify è attivo oggi. Dicci quale ti serve per prima e la mettiamo in cima alla lista.
Inizia a costruire con Returner.
Genera una key in Settings → API Keys, poi leggi la specifica o genera un client.