Eine REST-API,
auf der du aufbauen kannst.
Endpoints mit Bearer-Authentifizierung und Scopes für Retouren, Tracking, Retourenlabel und einen Retouren-Agenten, den du auf Deutsch fragst, mit Rate Limits pro Key. Die breitere programmierbare Plattform steht auf der Roadmap.
Einen Request testen.
Endpoint wählen. Request und Response aktualisieren sich daneben.
Eine Retoure abrufen
Liefert eine einzelne Retoure als JSON. {id} nimmt die Retourennummer (RET-####) oder die interne id. Erfordert 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 }
]
}Alle Endpoints.
/api/v1/returns/{id} Eine Retoure abrufen (JSON) · returns:read live/api/v1/returns/{id}/tracking Aktueller Tracking-Status · returns:read live/api/v1/returns/{id}/label Retourenlabel als PDF (302-Redirect) · labels:read live/api/v1/agent Retouren-Agent für Fragen in normalem Deutsch · returns:read live/api/v1/openapi.json OpenAPI-3.1-Spezifikation · public livereturn.* Signierte Webhooks: created · approved · received · refunded · exchanged · cancelled liveSo werden Requests autorisiert.
Bearer-Keys
Sende Authorization: Bearer ret_live_<key> bei jedem /api/v1/* Request mit. Der Key wird nur einmal bei der Erstellung angezeigt, und wir speichern nur einen Hash. Keys erstellst und widerrufst du unter Settings → API Keys.
Fehler
- 401 unbekannter oder widerrufener Key
- 403 dem Key fehlt der erforderliche Scope
- 404 keine solche Retoure in deinem Shop
- 429 Rate Limit überschritten (siehe
Retry-After)
Jeder Fehler antwortet mit JSON { error, message, code }: error und message sind dieselbe lesbare Zeichenkette; code ist ein stabiler maschinenlesbarer Slug
(unauthorized, forbidden, not_found, rate_limited, …) auf den du sicher verzweigen kannst.
Rate Limits
120 Requests pro Minute und Key. Jede Response trägt X-RateLimit-Limit, X-RateLimit-Remaining, und X-RateLimit-Reset; bei 429 kommt hinzu Retry-After.
Das kann die Schnittstelle.
Roadmap der Integrationen.
Shopify ist heute live. Sag uns, was für deinen Stack als Nächstes zählt, und wir priorisieren es.
Bau mit Returner.
Key unter Settings → API Keys erstellen, dann die Spezifikation lesen oder einen Client generieren.