Skip to main content

​
Return Helper API

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.

​
Available APIs

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.

​
Authentication

All API requests require an API key and token passed as request headers:
Getting your credentials:
  1. Log in to the Return Helper User Portal.
  2. Go to Settings → Signing Key and API Token.
  3. Your existing key-token pairs are listed here. You can also generate a new pair.
Signing Key, API Token and API Key in the User Portal

Signing Key, API Token and API Key in the User Portal

The same screen also shows your signing key (highlighted in the image above). This is a separate, Base64-encoded secret — it is not used to authenticate API requests. Instead, it verifies that incoming webhook notifications genuinely came from Return Helper. You can also read it programmatically with Get signing key. For how to use it, see Webhooks → Signature Verification.
Your API token and signing key are private. Never share them or expose them in client-side code.

​
Base URLs

​
Sandbox

​
Production

​
Idempotency

For state-changing requests (creating return shipments, inventories, etc.), include an idempotency key to prevent duplicate operations in the event of network retries.
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.

​
User-Agent Header

Include a User-Agent header so Return Helper support can identify your integration when investigating issues:
Example:
A full request header looks like:

​
OpenAPI Specification

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.

Download OpenAPI Specification

openapi.json — OpenAPI 3.1

​
Error Handling

Every response — success or failure — is wrapped in a common envelope:
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.

​
Failure modes

​
Sample — validation failure

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.

​
General Remarks

  • All dateTime parameters must be in ISO 8601 format, otherwise the API cannot parse them.
  • Date string parameters (e.g. createToStr, createFromStr) must also be ISO 8601; the time portion is ignored.
  • All timestamps returned by the API are in UTC.

​
Webhooks

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.