Skip to main content

​
Prerequisites

Before integrating with the Return Helper API, ensure you have:
  1. API credentials — see the Authentication section.
  2. A webhook notification endpoint ready to receive asynchronous events from Return Helper. If no notification endpoint is provided, label results and warehouse events will not be received.
  3. Read through this guide to understand the main return flow.

​
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.).

​
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.