Skip to main content

​
Before You Integrate

Integration responsibility is split between Return Helper and your team. Return Helper provisions credentials and connects your webhook endpoint; your engineering team builds the request signer and the webhook receiver. The two tables below show who owns what, followed by a step-by-step checklist a non-technical project lead can run through with their engineering team.

​
Who handles what

StepReturn HelperYour team
API key and tokenIssued in the User Portal under Settings → Signing Key and API TokenStore securely; load into your server config
Sandbox accessSandbox base URLs are documented in Base URLsRun all integration testing against sandbox first
Webhook receiverProvides the signing key used for signature verificationBuild an HTTPS endpoint, parse the raw body, verify the signature, respond 200 quickly
Webhook endpoint registrationWe activate your endpoint after you submit the setup request formSubmit the Webhook Setup Request Form once your endpoint is publicly reachable
Idempotency—Deduplicate using notificationId (see Webhooks)
Production go-liveWe issue production credentials and switch your registered endpoint to production after sandbox validationNotify support when sandbox testing is complete and you are ready for production traffic

​
Seller checklist

Work through these items in order before calling any state-changing endpoint:
  1. Obtain API credentials. Log in to the User Portal and copy the API key and API token from Settings → Signing Key and API Token. The same screen shows the signing key used to verify webhook signatures.
  2. Decide your environment. Start in sandbox (UAT). Production base URLs are only used after sandbox validation — see Base URLs.
  3. Build your webhook receiver. Stand up an HTTPS endpoint that parses the raw POST body, verifies the returnhelper-signature header using the signing key, deduplicates on notificationId, and responds 200 OK quickly. Reference code is in Webhooks → Signature Verification.
  4. Register your endpoint with us. Submit the Webhook Setup Request Form once the endpoint is reachable from the public internet. We complete the connection — there is no self-serve registration API today.
  5. Test end-to-end in sandbox. Walk through label creation, warehouse arrival, and post-arrival handling using the flows described in the rest of this guide. Confirm the corresponding webhook events arrive at your receiver.
  6. Request production go-live. When sandbox testing is complete, contact support to swap your credentials and registered endpoint to production.
Until step 4 is complete, label results and warehouse events have nowhere to go. Without a registered webhook endpoint the API will still accept requests, but you cannot retrieve generated labels or learn when shipments arrive.

​
Return Flow Overview

A typical return has three stages:
  1. Before warehouse arrival — Create a return shipment and receive a shipping label.
  2. Warehouse arrival — The package is scanned in; images are uploaded; the shipment becomes a Return Inventory record.
  3. Post-arrival handling — Instruct the warehouse how to handle the inventory (dispose, resend, recall, VAS, etc.).

​
End-to-End Recipes

Three compact recipes that map each lifecycle moment to the exact API call you make, the webhook event you listen for, and the next action you take. Each recipe links to the prose section below for the full explanation.

​
Recipe 1 — Create a return label

StepWhat you doWebhook (action)Next action
1POST /api/ReturnShipment/createReturnShipment—Read shipmentId and labelRequestStatusCode: queued from the synchronous response.
2 (success)(wait)labelGeneratedRead labelUrl and trackingNumber from the webhook payload; deliver the label to the customer. Match using shipmentId, not labelId.
2 (failure)(wait)labelGenerated with labelRequestStatusCode: failedInspect failReasons and errorMessages; surface the failure to your CS / ops team.
Detailed flow: Requesting a Return Label.

​
Recipe 2 — Receive a warehouse arrival

No outbound API call needed — wait for the warehouse to report the events.
StepWebhook (action)Next action
1markShipmentArriveMatch by shipmentId to the Return Shipment you created earlier.
2newInventoryCreated — one event per resulting Return Inventory (a single shipment can produce more than one)Store the new returnInventoryId against the matching shipment in your system.
3changeLineItemImage whenever the warehouse adds or replaces an imageRefresh the cached image URL list for that returnInventoryId.
Variant — Unknown ShipmentassignUnknown arrives instead of steps 1+2 when a parcel turns up without a seller-created Return ShipmentTreat as a brand-new Return Inventory; the payload already contains returnInventoryId, shipmentId, returnRequestId, and any pre-assignment images.
Detailed flow: Return Inventory at Warehouse Arrival.

​
Recipe 3 — Send a handling instruction

Pick the row that matches the operation you want; the API call and the webhook to wait for are different for each.
OperationAPI callWebhook (action)Next action
Dispose / On-holdPOST /api/ReturnInventory/UpdateReturnInventoryHandling with the dispose or on-hold handling codecompleteInventoryHandlingInventory closed; no further action needed.
ResendPOST /api/Resend/createResend referencing one or more returnInventoryIdupdateResendStatusTrack the resend’s outbound shipment until delivered to the buyer.
RecallPOST /api/Recall/createRecallByReturnInventoryId with up to 100 returnInventoryIdrecallUpdateStatusTrack the shipment until the inventory arrives at the Hong Kong consolidation warehouse.
VASPOST /api/Vas/CreateByReturnInventoryId with the returnInventoryId and the VAS types you wantvasUpdated (and splitLineItem if the VAS splits the inventory into multiple pieces)Re-read the inventory record. If the VAS produced a split, each new piece arrives as its own returnInventoryId with its own RMA.
To withdraw a handling instruction before it is processed, call the cancel endpoint for the same operation (e.g. POST /api/ReturnInventory/CancelReturnInventoryHandling). Detailed flow: Handling Instructions.

​
Requesting a Return Label

Label creation is asynchronous. The flow is:
  1. Call Create Return Shipment to create a return shipment record and queue a label request.
  2. Return Helper generates the label and delivers the result to your webhook notification endpoint via the label notification event.
You must have a webhook endpoint registered to receive label results. Without it, you will have no way to retrieve the generated label.

​
RMA (Return Merchandise Authorization)

When a shipment enters a Return Helper warehouse it is assigned a globally unique RMA. Return Helper uses RMA as the primary communication identifier instead of the carrier tracking number, for two reasons:
  • Tracking numbers can be duplicated across carriers, or even within the same carrier.
  • When a parcel is split via VAS, each resulting parcel receives its own RMA.
Normal RMA format: 
<warehouse prefix>-<warehouse ID>-<YYMMDD>-<env letter><sequence up to 5 digits>-<check digits>
Example: TWN-20-230101-D12345-36 Split RMA format (after a VAS split): 
<warehouse prefix>-<warehouse ID>-<YYMMDD>-<env letter><sequence up to 5 digits>-<split sequence 2 digits>-<check digits>
Example: TWN-20-230101-D12345-01-36

​
Return Inventory at Warehouse Arrival

When a return shipment arrives at the warehouse, it is marked received and converted into one or more Return Inventory records, each with a unique returnInventoryId.

​
Type 1 — Seller-initiated shipment

  1. Seller created the shipment via the API and provided a label.
  2. Warehouse marks it received → warehouseMarkShipmentArrivedV2 webhook is sent, followed by inventoryCreated (which includes returnInventoryId).
  3. If a single label covers multiple packages, each package becomes a separate Return Inventory record sharing the same shipmentId and returnRequestId. One inventoryCreated event is sent per inventory.
  4. Inventory images are uploaded next and delivered via changeLineItemImage.

​
Type 2 — Unknown shipment assigned to seller

  1. The shipment arrived without a seller-created record but was identified as belonging to a seller.
  2. assignUnknown webhook is sent, including the return inventory payload, returnInventoryId, shipmentId, and returnRequestId.
  3. Multiple inventoryCreated events may follow if the package contains multiple items.
  4. Images captured before assignment are included in assignUnknown; any subsequent changes arrive via changeLineItemImage.

​
Inventory Images

When images are uploaded (or the image list changes), the changeLineItemImage webhook is sent containing the image URL list.

​
Handling Instructions

Once a Return Inventory record exists, instruct the warehouse what to do with it:

​
Dispose

Call Update Return Inventory Handling with a dispose handling type. Use Cancel Return Inventory Handling to withdraw the instruction.

​
On-hold

Call Update Return Inventory Handling with an on-hold handling type.

​
Resend

  1. Call Create Resend with a list of returnInventoryId values.
  2. Receive the resend tracking number via the resend webhook notification.
  3. Call Cancel Resend if the resend is no longer needed.

​
Recall

  1. Call Create Recall by Return Inventory IDs with up to 100 returnInventoryId values.
  2. Tracking updates and pick-up status changes are delivered via the recall webhook notification.

​
Value-Added Services (VAS)

  1. Call Create VAS with the returnInventoryId and the required VAS types.
  2. Results are delivered via the UpdateVas webhook notification.

​
Custom Fields

Custom fields let you attach arbitrary key-value metadata to a return. They are stored but not processed by Return Helper — they are returned to you in relevant webhook notifications.
  • Type: Dictionary<string, string>
  • Maximum 24 custom fields per return.
{
  "customFieldMap": {
    "customerId": "buyer123",
    "dateOfPurchase": "2024-07-01"
  }
}
Custom fields are available in Create Return Shipment and are echoed back in the warehouseMarkShipmentArrivedV2 notification.

​
FBA (Fulfilled by Amazon) Returns

Customers can send FBA products to a Return Helper warehouse for processing (restock, replenish, recall, dispose, etc.). Typical FBA workflow:
  1. Call Create FBA Shipment to notify Return Helper and send the products to the warehouse.
  2. The shipment is received, put away as FBA inventory with fnsku and quantity, and delivered via webhook.
  3. Check existing FBA inventory with Get FBA Warehouse Inventory List.
  4. Create instructions via Create FBA Instructions (replenishment requires additional shipping information not currently available in the API).
  5. Return Helper processes the instruction and notifies you of results via webhook.
  6. Check instruction status via the relevant Get FBA Instruction Detail endpoint (Recall, Dispose, Restock, Others).
Retrieving historical FBA data (for existing portal users migrating to the API):
  1. Use List FBA Shipments to retrieve past shipments within a date range, collecting fbaShipmentId values.
  2. Call Get FBA Shipment Item List to get items, FNSKU, and quantities per shipment.
  3. Use Get FBA Warehouse Inventory List with an FNSKU to see current inventory.
  4. Use List FBA Instructions to find past instructions.
  5. Use Get FBA Instruction Item List per instruction for line-item detail.
Once you have retrieved historical data, rely on regular API calls and webhook events going forward rather than polling.

​
Retrieving Historical Data

This section is for existing Return Helper Portal users who are migrating to the API. If you are integrating from scratch, all necessary data is exchanged through normal API calls and webhook events — you do not need to retrieve historical data.
Retrieving historical return shipment data: Use List Shipments to retrieve past return shipments within a date range. Retrieving historical return inventory data: Use List Return Inventories to retrieve past return inventory records within a date range. For FBA historical data, see the Retrieving historical FBA data section above. Once you have retrieved all historical data, rely on regular API calls and webhook events going forward rather than continuously polling for history data.

​
Response Structure

Every API response contains a meta object indicating the result status. Successful response (status: 200): 
{
  "apiBalances": [
    {
      "apiBalanceId": 7,
      "currencyCode": "usd",
      "balance": 2044.233
    }
  ],
  "correlationId": "0HM9VIKSKH2CB:00000002",
  "meta": {
    "status": 200,
    "data": {},
    "errorCode": null,
    "error": {}
  },
  "totalNumberOfRecords": 1
}
Failed response (e.g. invalid warehouseId): 
{
  "correlationId": "0HM9VIKSKH2CF:00000002",
  "meta": {
    "status": 400,
    "data": {},
    "errorCode": "VALIDATION_FAILED",
    "error": {
      "warehouseId": "The value 'invalid' is not valid."
    }
  }
}
Any status value other than 200 means the request did not complete successfully. The errorCode and error fields provide details.