Return Helper provides a suite of APIs for managing e-commerce product returns end-to-end — from return request creation through shipment tracking, label generation, and warehouse processing.
The API is designed for server-to-server integration only. Do not call these endpoints directly from client-side code.
User API — Authenticated endpoints for merchants and partners to manage return requests, shipments, labels, inventory, and account settings.Public API — Reference data endpoints exposing lookup values such as service types, warehouse lists, status codes, and supported countries.
For state-changing requests (creating return shipments, inventories, etc.), include an idempotency key to prevent duplicate operations in the event of network retries.
x-returnhelper-idempotency-key: YOUR_UNIQUE_KEY
Generate a fresh UUID (or similarly unique string) for each distinct transactional request. The server recognises repeated submissions of the same key and executes the operation only once, preserving data integrity.
The full API specification is available as an OpenAPI 3.1 document. You can download it and import it directly into API clients such as Postman or Insomnia, or use it to generate client SDKs with tools like OpenAPI Generator.
For successful calls the business payload is included as additional top-level fields alongside correlationId and meta (for example, getAllCountries returns { correlationId, meta, countries: [...] }). Always check meta.errorCode before reading the payload — the API uses a soft-error convention where validation failures arrive as HTTP 200 with meta.status: 400 and a populated meta.errorCode.
{ "correlationId": "0HNLB2U6T1QG1:00000001", "meta": { "status": 400, "data": {}, "errorCode": "VALIDATION_FAILED", "error": { "returnInventoryId": "'return Inventory Id' must not be empty." } }}
Do not branch on the wire HTTP status alone. A 200 OK response can still represent a logical failure — always inspect meta.status and meta.errorCode.
When integrating, log the correlationId from every response. Return Helper support uses it to trace requests when investigating issues.For the full list of meta.errorCode values the API can emit — including business-rule errors like TRACKING_ALREADY_EXIST, ACCOUNT_IS_BLOCKED, and others not covered by the table above — see the Error codes reference.
Label results and warehouse events (shipment arrival, inventory creation, image uploads, etc.) are delivered asynchronously via webhook notifications. You must register a notification endpoint to receive these events.See the Webhooks section for the full list of notification event types and their payloads.
