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.

Announcements

Rate limit: 1 request per second

From 1 November 2026The API will accept at most one request per second. Check your call rate before peak season.

Seller reference number on Create resend order

Action required if you set resendNumberResend search opens to every account. resendNumber becomes read-only.

New webhook event: Transaction added

From 5 October 2026Every charge, refund and top-up is sent to your webhook endpoint.

API rate limit: 1 request per second

From 1 November 2026, Return Helper enforces a rate limit of 1 request per second on the API, to enhance service stability for every integration through peak season.

Pace your calls so you send no more than one request per second.
Use webhooks to receive shipment, inventory and resend updates instead of polling list endpoints.

Seller reference number on Create resend order

Create resend order (User API) will accept an optional sellerReferenceNumber, as Create resend by SKU already does. Every account — not only Enterprise — will then be able to find resends with Search resend by seller reference number. sellerReferenceNumber is optional, so existing integrations keep working. One change is breaking: resendNumber becomes a read-only value generated by Return Helper.

Action required if your integration sets resendNumber on Create resend order — for example to your invoice or order ID. Move that value to sellerReferenceNumber before Milestone 2. If you never set resendNumber, no action is needed.

Milestone	Date	What changes
Milestone 1	To be announced	`sellerReferenceNumber` is accepted on Create resend order. You can still set `resendNumber`. If you set `resendNumber` but not `sellerReferenceNumber`, Return Helper copies your `resendNumber` into `sellerReferenceNumber`, so the resend is searchable with no change on your side.
Milestone 2	3 months after Milestone 1	Requests that set `resendNumber` are rejected. `resendNumber` is always generated by Return Helper.

To migrate, between Milestone 1 and Milestone 2:

Send your own reference in sellerReferenceNumber instead of resendNumber.
If you match resend status update webhooks or your own records on resendNumber, match on sellerReferenceNumber instead.

Unlike resendNumber, sellerReferenceNumber is not unique — Return Helper does not reject a repeated value. To avoid duplicate resends when retrying, send an x-returnhelper-idempotency-key header. We will publish the Milestone 1 date here and in the Changelog.

New webhook event: Transaction added

From 5 October 2026, Return Helper sends a Transaction added event to every registered webhook endpoint each time a transaction is posted to your account. You don’t need to register anything new. Transactions posted before 5 October 2026 are not sent.

Action required if your endpoint returns a non-2xx status for events it doesn’t recognise. Failed deliveries are retried, and after 10 consecutive failures, delivery to your endpoint is suspended for 24 hours, including all other events. Return 2xx for events you don’t handle.

Changelog

Announcement

Transaction added webhook

Announced: Transaction added webhook event, sent from 5 October 2026. See the announcement.

New

Cancel return label

Cancel a return label with Cancel return label. To correct a shipment, cancel its label and create a new return shipment.

Announcement

Rate limit and create resend upgrade

Announced: API rate limit of 1 request per second, effective 1 November 2026.
Announced: sellerReferenceNumber on Create resend order; resendNumber will become read-only.

New

Self-service webhook endpoints

Manage your webhook notification endpoints yourself with Add a notification endpoint, List notification endpoints and Delete a notification endpoint.

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:

x-rr-apikey: YOUR_API_KEY
x-rr-apitoken: YOUR_API_TOKEN
Content-Type: application/json

Getting your credentials:

Log in to the Return Helper User Portal.
Go to Settings → Signing Key and API Token.
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

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

Endpoint	Base URL
User API	`https://api.returnshelper.com/uat/user`
Public API	`https://api.returnshelper.com/uat/public`

Production

Endpoint	Base URL
User API	`https://api.returnhelpercentre.com/v1/user`
User API (China)	`https://api.returnhelperchina.com/user`
Public API	`https://api.returnhelpercentre.com/v1/public`

Idempotency

The endpoints below accept an x-returnhelper-idempotency-key header, so that a retried request is processed only once.

x-returnhelper-idempotency-key: YOUR_UNIQUE_KEY

Generate a fresh UUID (or similarly unique string) for each distinct request, and send the same key only when retrying that request. The header is optional. A request without it is processed normally, with no protection against duplicates. A request that reuses the key of a completed request is rejected instead of being processed again — see Idempotency key failures.

Endpoint	Route
Create return shipment	`POST /api/ReturnShipment/createReturnShipment`
Cancel return label	`POST /api/Label/CancelLabel`
Create resend order	`POST /api/Resend/createResend`
Create resend by SKU	`POST /api/Resend/createResendBySku`
Cancel resend order	`POST /api/Resend/cancelResend`
Assign SKU to return inventory	`POST /api/ReturnInventory/assignReturnInventorySku`
Add a notification endpoint	`POST /api/Notification/Add`
Delete a notification endpoint	`POST /api/Notification/Delete`

Other endpoints ignore the header.

User-Agent Header

Include a User-Agent header so Return Helper support can identify your integration when investigating issues:

User-Agent: {app name}/{app version} (Platform={os version}; Runtime={runtime version}; Language={language})

Example:

User-Agent: CompanyABCApi/2024.16.0 (Platform=Unix/13.4.0; Runtime=8.0.2; Language=CSharp12)

A full request header looks like:

x-rr-apikey: YOUR_API_KEY
x-rr-apitoken: YOUR_API_TOKEN
Content-Type: application/json
x-returnhelper-idempotency-key: YOUR_UNIQUE_KEY
User-Agent: YourApp/1.0.0 (Platform=Linux/5.15; Runtime=8.0.2; Language=CSharp12)

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:

{
  "correlationId": "0HNL9S3BA31VM:00000001",
  "meta": {
    "status": 200,
    "data": {},
    "errorCode": null,
    "error": {}
  }
}

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

Failure	Wire HTTP	Body
Missing or invalid `x-rr-apikey` / `x-rr-apitoken`	401	`meta.status: 401`, `meta.error.message` describes the auth failure
Validation failure (missing field, wrong type, business rule violation)	200	`meta.status: 400`, `meta.errorCode: "VALIDATION_FAILED"`, `meta.error` keyed by request field
Success	200	`meta.status: 200`, `meta.errorCode: null`, payload at top level

Sample — validation failure

{
  "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.

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.

Contact Technical Support

For technical questions or integration issues, email support@returnhelper.com. Include the following so we can investigate:

The correlationId from the response
The environment (sandbox or production) and the endpoint you called
The time of the request, including the time zone
The request body and the response you received

Do not include your API token or signing key.

Overview

Introduction

Return Helper API

Announcements

Rate limit: 1 request per second

Seller reference number on Create resend order

New webhook event: Transaction added

API rate limit: 1 request per second

Seller reference number on Create resend order

New webhook event: Transaction added

Changelog

Available APIs

Authentication

Base URLs

Sandbox

Production

Idempotency

User-Agent Header

OpenAPI Specification

Download OpenAPI Specification

Error Handling

Failure modes

Sample — validation failure

General Remarks

Webhooks

Contact Technical Support

​Return Helper API

​Announcements

Rate limit: 1 request per second

Seller reference number on Create resend order

New webhook event: Transaction added

​API rate limit: 1 request per second

​Seller reference number on Create resend order

​New webhook event: Transaction added

​Changelog

​Available APIs

​Authentication

​Base URLs

​Sandbox

​Production

​Idempotency

​User-Agent Header

​OpenAPI Specification

Download OpenAPI Specification

​Error Handling

​Failure modes

​Sample — validation failure

​General Remarks

​Webhooks

​Contact Technical Support

Return Helper API

Announcements

API rate limit: 1 request per second

Seller reference number on Create resend order

New webhook event: Transaction added

Changelog

Available APIs

Authentication

Base URLs

Sandbox

Production

Idempotency

User-Agent Header

OpenAPI Specification

Error Handling

Failure modes

Sample — validation failure

General Remarks

Webhooks

Contact Technical Support