Webhooks & Notifications - Return Helper API

Overview

Webhooks deliver asynchronous notifications when events occur in the Return Helper system — for example, when a label is generated or a shipment arrives at the warehouse. Your server must expose an HTTPS endpoint to receive these POST requests.

Expect new fields. Return Helper adds fields to webhook payloads without prior notice. Do not strictly validate payload schemas — ignore fields you do not recognise and still respond with 2xx.

Setting Up Your Webhook Endpoint

Endpoint Requirements

Before registering your endpoint, make sure it meets the following requirements:

Publicly accessible — the URL must be reachable from the internet (no VPN, localhost, or internal-only addresses)
HTTPS — the endpoint must be served over HTTPS with a valid TLS certificate
HTTP POST — the endpoint must accept POST requests with a application/json body
Respond with 2xx — your server must return a 2xx status promptly after receiving the request; any other status code or a timeout is treated as a failed delivery
Fast response — process the event asynchronously if needed; do not perform heavy work before responding, to avoid delivery timeouts
Accept events you don’t handle — return 2xx for any category / action your handler doesn’t process. New events are added over time and are sent to every registered endpoint.

Registering Your Endpoint

To	Call
Register an endpoint	Add a notification endpoint
See your registered endpoints	List notification endpoints
Remove an endpoint	Delete a notification endpoint

Deploy your handler before you register it. Return Helper sends a signed verification request to the URL, and the endpoint is stored only if it responds with a 2xx status within 30 seconds. Each registered endpoint receives every event for your account. Filter on the category and action fields on your side. Sandbox and production are registered separately. Call the API in each environment you want notifications from, using that environment’s credentials.

Event Delivery

Timing — Events may arrive a few seconds after the triggering action, and in rare cases up to a few minutes later. Duplicate events — Your endpoint may receive the same event more than once. Track processed notificationId values to deduplicate; notificationId is unique per event and present on every webhook notification, so it is a stable idempotency key on its own. Event ordering — Delivery order is not guaranteed. Design your handler to process events in any order. For example, inventoryCreated may arrive before warehouseMarkShipmentArrivedV2. Use the API to fetch any objects referenced in events you receive out of sequence. Each event includes an eventTime field in ISO 8601 format.

Notification Headers

Every webhook request includes these headers:

Header	Type	Description
`RETURNHELPER-TRIGGERED-AT`	string	ISO 8601 timestamp in UTC, for example `2026-08-14T09:31:02.1234567Z`. This is the value used in signature verification.
`RETURNHELPER-API-ID`	string	The `apiId` of the account the notification belongs to. Retrieve yours with Get API account information.
`RETURNHELPER-API-NAME`	string	The `apiName` of that account.
`ReturnHelper-Signature`	string	HMAC-SHA256 signature for verification — see Signature Verification.

Legacy headers

These headers are still sent on every notification and are not being removed. New integrations should read the headers above instead.

Legacy header	Replaced by
`Timestamp`	`RETURNHELPER-TRIGGERED-AT` — same value, character for character.
`x-returnhelper-apiname`	`RETURNHELPER-API-NAME` — same value.

HTTP header names are case-insensitive, and some frameworks normalise them. The casing above is what Return Helper sends on the wire; if your framework lowercases incoming header names, match them case-insensitively.

Signature Verification

Always verify the signature before processing any payload. Use the raw request body — any transformation (e.g. by a framework that re-serialises JSON) will cause verification to fail.

Your signing key is provided by Return Helper (it is Base64-encoded). Store it securely and never expose it. You can find it in the User Portal on the same screen as your API key and token — see the screenshot under Authentication — or read it programmatically with Get signing key.

Worked Example

Given the following incoming request: Headers:

{
  "content-type": "application/json; charset=utf-8",
  "ReturnHelper-Signature": "gXJRba6qE2rCQqJc8WEou2i8cCl0STp2AjH+y/R6ltw=",
  "RETURNHELPER-TRIGGERED-AT": "2024-01-12T09:23:08.4863561Z",
  "RETURNHELPER-API-ID": "12345",
  "RETURNHELPER-API-NAME": "Acme Returns",
  "Timestamp": "2024-01-12T09:23:08.4863561Z"
}

Body (raw JSON, must not be re-serialised):

{"label":{"regions":{"RHCN":"https://label.returnhelperchina.com/label/202401/10595-S240112-0000001-pqk2pvydgxp.pdf"},"labelId":31033,"shipmentId":30385,"apiId":33,"refKey":"S240112-0000001","labelRequestStatusCode":"success","serviceType":"RETURN_ENDICIA_USPS_GROUND_ADVANTAGE_NJ","trackingNumber":"9434611899562082901137","labelUrl":"https://label-service-dev-files.returnshelper.com/label/202401/10595-S240112-0000001-pqk2pvydgxp.pdf","error":null,"qrcodeUrl":null,"qrcodeError":null,"correlationId":null,"cancelCutoffTime":"2024-02-11T09:21:24.0795","meta":null},"category":"labelGenerated","action":"labelGenerated","eventTime":"2024-01-12T09:23:08.4862743Z"}

Step-by-Step Verification

Step 1 — Extract the signature from the ReturnHelper-Signature header (for comparison at the end):

gXJRba6qE2rCQqJc8WEou2i8cCl0STp2AjH+y/R6ltw=

Step 2 — Extract the timestamp from the RETURNHELPER-TRIGGERED-AT header:

2024-01-12T09:23:08.4863561Z

Step 3 — Build the string_to_sign Concatenate these four values in order (no separator):

HTTP method: POST
Your notification endpoint URL: https://s2024-01-12.free.beeceptor.com
The RETURNHELPER-TRIGGERED-AT value from Step 2
The raw JSON body

The resulting concatenated string:

POSThttps://s2024-01-12.free.beeceptor.com2024-01-12T09:23:08.4863561Z{"label":{"regions":...},...}

Then Base64-encode the entire concatenated string. The result is the string_to_sign:

UE9TVGh0dHBzOi8vczIwMjQtMDEtMTIuZnJlZS5iZWVjZXB0b3IuY29tMjAyNC0wMS0xMlQwOToyMzowOC40ODYzNTYxWnvigJxsYWJlbOKAnTp74oCccmVnaW9uc+KAnTp74oCcUkhDTuKAnTrigJxodHRwczovL2xhYmVsLnJldHVybmhlbHBlcmNoaW5hLmNvbS9sYWJlbC8yMDI0MDEvMTA1OTUtUzI0MDExMi0wMDAwMDAxLXBxazJwdnlkZ3hwLnBkZuKAnX0s4oCcbGFiZWxJZOKAnTozMTAzMyzigJxzaGlwbWVudElk4oCdOjMwMzg1LOKAnGFwaUlk4oCdOjMzLOKAnHJlZktleeKAnTrigJxTMjQwMTEyLTAwMDAwMDHigJ0s4oCcbGFiZWxSZXF1ZXN0SWTigJ06MTA1OTUs4oCcbGFiZWxSZXF1ZXN0U3RhdHVzQ29kZeKAnTrigJxzdWNjZXNz4oCdLOKAnHNlcnZpY2VUeXBl4oCdOuKAnFJFVFVSTl9FTkRJQ0lBX1VTUFNfR1JPVU5EX0FEVkFOVEFHRV9OSuKAnSzigJx0cmFja2luZ051bWJlcuKAnTrigJw5NDM0NjExODk5NTYyMDgyOTAxMTM3IizigJxsYWJlbFVybOKAnTrigJxodHRwczovL2xhYmVsLXNlcnZpY2UtZGV2LWZpbGVzLnJldHVybnNoZWxwZXIuY29tL2xhYmVsLzIwMjQwMS8xMDU5NS1TMjQwMTEyLTAwMDAwMDEtcHFrMnB2eWRneHAucGRm4oCdLOKAnGVycm9y4oCdOm51bGws4oCccXJjb2RlVXJs4oCdOm51bGws4oCccXJjb2RlRXJyb3LigJ06bnVsbCzigJxjb3JyZWxhdGlvbklk4oCdOm51bGws4oCcY2FuY2VsQ3V0b2ZmVGltZeKAnTrigJwyMDI0LTAyLTExVDA5OjIxOjI0LjA3OTUiLOKAnG1ldGHigJ06bnVsbH0s4oCcY2F0ZWdvcnnigJ064oCcbGFiZWxHZW5lcmF0ZWTigJ0s4oCcYWN0aW9u4oCdOuKAnGxhYmVsR2VuZXJhdGVk4oCdLOKAnGV2ZW50VGltZeKAnTrigJwyMDI0LTAxLTEyVDA5OjIzOjA4LjQ4NjI3NDNa4oCdfQ==

Step 4 — Compute the HMAC-SHA256 signature Using the example signing key (your actual key will be different):

PEnA0mzKb7fUlGfMgCGhXPjPmPGvW70UU8bkNKdG78WDrQRwzFa572e2JsFIE1e4PLaP9h/ZEvERSR0FBDYNlQ==

Operations:

Decode the string_to_sign (from Step 3) from Base64 → byte array
Decode your signing key from Base64 → byte array
Compute HMAC-SHA256 using the signing key bytes over the string_to_sign bytes → signature byte array
Base64-encode the signature byte array

Expected result:

gXJRba6qE2rCQqJc8WEou2i8cCl0STp2AjH+y/R6ltw=

Step 5 — Compare signatures Compare the signature computed in Step 4 with the one extracted in Step 1. Use a constant-time string comparison to prevent timing attacks. Additional security: Reject events where eventTime differs from your system clock by more than 15 minutes (replay attack protection).

Sample Code

// Required imports (add at the top of your file):
//   import java.security.InvalidKeyException;
//   import java.security.NoSuchAlgorithmException;
//   import javax.crypto.Mac;
//   import javax.crypto.spec.SecretKeySpec;
//   import org.apache.commons.codec.binary.Base64;

class Main {
  private static final String CHARACTER_ENCODING = "UTF-8";
  final static String ALGORITHM = "HmacSHA256";

  public static void main(String[] args) throws Exception {
    String payload   = "<body JSON string>";
    String action    = "<action>";           // always "POST"
    String url       = "<url>";              // your notification endpoint
    String timestamp = "<timestamp>";        // from RETURNHELPER-TRIGGERED-AT header

    String data = new String(
      Base64.encodeBase64((action + url + timestamp + payload).getBytes(CHARACTER_ENCODING))
    );

    String base64Key  = "<signing key>";
    String signature  = sign(data, base64Key);
    System.out.println(signature);
  }

  private static String sign(String data, String secretKey)
      throws NoSuchAlgorithmException, InvalidKeyException {
    Mac mac = Mac.getInstance(ALGORITHM);
    mac.init(new SecretKeySpec(Base64.decodeBase64(secretKey), ALGORITHM));
    byte[] signature = mac.doFinal(Base64.decodeBase64(data));
    return new String(Base64.encodeBase64(signature), CHARACTER_ENCODING);
  }
}

// Node.js built-in module. Import at the top of your file:
//   import * as crypto from 'node:crypto';   // ESM
//   const crypto = require('node:crypto');   // CommonJS

function sign(data, secretKey) {
  const key        = Buffer.from(secretKey, 'base64');
  const hmac       = crypto.createHmac('sha256', key);
  const dataBuffer = Buffer.from(data, 'base64');
  hmac.update(dataBuffer);
  return hmac.digest('base64');
}

async function main() {
  const payload   = '<body JSON string>'; // raw request body
  const action    = '<action>';           // always "POST"
  const url       = '<url>';              // your notification endpoint
  const timestamp = '<timestamp>';        // from RETURNHELPER-TRIGGERED-AT header

  const encodedData = Buffer.from(action + url + timestamp + payload).toString('base64');
  const base64Key   = '<signing key>';
  const signature   = sign(encodedData, base64Key);

  console.log('Signature:', signature);
}

main().catch(console.error);

// Node.js built-in module. Import at the top of your file:
//   import * as crypto from 'node:crypto';

function sign(data: string, secretKey: string): string {
  const key         = Buffer.from(secretKey, 'base64');
  const hmac        = crypto.createHmac('sha256', key);
  const decodedData = Buffer.from(data, 'base64');
  hmac.update(decodedData);
  return hmac.digest('base64');
}

function main() {
  const payload   = '<body JSON string>'; // raw request body
  const action    = '<action>';           // always "POST"
  const url       = '<url>';              // your notification endpoint
  const timestamp = '<timestamp>';        // from RETURNHELPER-TRIGGERED-AT header

  const encodedData = Buffer.from(action + url + timestamp + payload, 'utf-8').toString('base64');
  const base64Key   = '<signing key>';
  const signature   = sign(encodedData, base64Key);

  console.log(signature);
}

main();

public class Main {
    private static final String ALGORITHM = 'HmacSHA256';

    public static void main() {
        String payload   = '<body JSON string>'; // raw request body
        String action    = '<action>';            // always 'POST'
        String url       = '<url>';               // your notification endpoint
        String timestamp = '<timestamp>';         // from RETURNHELPER-TRIGGERED-AT header

        Blob data        = EncodingUtil.base64Encode(
                               Blob.valueOf(action + url + timestamp + payload));
        String base64Key = '<signing key>';
        String signature = sign(data, base64Key);
        System.debug(signature);
    }

    private static String sign(Blob data, String secretKey) {
        Blob macKey   = EncodingUtil.base64Decode(secretKey);
        Blob sigBytes = Crypto.generateMac(ALGORITHM, data, macKey);
        return EncodingUtil.base64Encode(sigBytes);
    }
}

Retry Mechanism

Respond with a 2xx HTTP status code to acknowledge receipt. Non-2xx responses trigger retries. After 10 consecutive failures, notification delivery to your endpoint is suspended for 24 hours.

Common Body Fields

All notification bodies share these top-level fields:

Field	Type	Description
`category`	string	Notification category (see table below)
`action`	string	Specific event action
`eventTime`	string	ISO 8601 timestamp of the event
`version`	string	Notification schema version
`notificationId`	string	Unique per event. Present on every webhook notification — use this as your idempotency key.

Notification Event Reference

Notification	`category`	`action`	Description
Label result	`labelGenerated`	`labelGenerated`	Label generation result (success or failure)
Warehouse shipment arrived (v2)	`rsl`	`markShipmentArrive`	Shipment received at warehouse (current version)
Inventory created	`newInventoryCreated`	`newInventoryCreated`	New return inventory created
Image updated	`rrli`	`changeLineItemImage`	Line item image added, changed, or removed
Unknown shipment assigned	`rsl`	`assignUnknown`	Unknown shipment assigned to seller
Recall status update	`recall`	`recallUpdateStatus`	Recall tracking or pick-up status changed
Resend status update	`resend`	`updateResendStatus`	Resend tracking or status changed
VAS update	`rrliv`	`vasUpdated`	Value-added service completed or updated
Inventory handling complete	`rinv`	`completeInventoryHandling`	Handling instruction completed
Inventory recalibrated	`completeRecalibrate`	`completeRecalibrate`	Warehouse updated inventory dimensions/weight
Inventory meta updated	`updateReturnInventoryMeta`	`updateReturnInventoryMeta`	Warehouse or user added/updated meta data
RMA updated	`notifyUserRmaSwapped`	`notifyUserRmaSwapped`	Warehouse corrected an RMA assignment
SKU updated	`userUpdateReturnInventorySku`	`userUpdateReturnInventorySku`	Seller updated inventory SKU
Split line item	`lineItemVasReturnInventoryLineItem`	`splitLineItem`	VAS split a parcel into multiple inventories
Warehouse remarks updated	`warehouseUpdateWarehouseRemarks`	`warehouseUpdateWarehouseRemarks`	Warehouse updated remarks on a return request
Buyer return label generated	`buyerReturnRrLabel`	`buyerReturnLabelGenerated`	Branded return portal label generated for buyer
Shopify buyer return created	`shopifyBuyerCreateReturn`	`shopifyBuyerCreateReturn`	Buyer created a return via Shopify integration
Consolidate shipping cost updated	`consolidateShippingOrderShippingFeeUpdated`	`consolidateShippingOrderShippingFeeUpdated`	Consolidated shipping order cost updated
Consolidate shipping all packed	`consolidateShippingOrderInventoryAllPacked`	`consolidateShippingOrderInventoryAllPacked`	All inventories packed for a consolidated order
Consolidate shipment sent	`consolidateShippingShipmentSent`	`consolidateShippingShipmentSent`	Consolidated shipment dispatched to carrier
Consolidate shipping AWB updated	`consolidateShippingShipmentShipped`	`consolidateShippingShipmentShipped`	Consolidated shipment AWB updated
Consolidate shipment arrived	`consolidateShippingShipmentArrived`	`consolidateShippingShipmentArrived`	An RH warehouse shipment arrived and was charged
Consolidate order completed	`consolidateShippingOrderCompleted`	`consolidateShippingOrderCompleted`	Every item in a consolidated order shipped
Consolidate order cancelled	`consolidateShippingOrderCancelled`	`consolidateShippingOrderCancelled`	Consolidated order force-cancelled by warehouse
Transaction added	`transaction`	`addTransaction`	A charge, refund, or top-up was posted to your account

Notification Payloads

Label Result

Sent when a return label request completes (success or failure).

Always use shipmentId to match labels to shipments in your system — do not use labelId. In rare cases a carrier failure causes a new label (with a new labelId) to be issued for the same shipmentId.

category: labelGenerated / action: labelGenerated Key fields in label:

Field	Description
`labelId`	Label identifier (do not use for matching — see warning above)
`shipmentId`	Shipment identifier (use this for matching)
`apiId`	Seller API ID
`refKey`	Shipment reference key
`labelRequestStatusCode`	`"success"` or `"fail"`
`serviceType`	Carrier service type used
`trackingNumber`	Carrier tracking number (on success)
`labelUrl`	URL to download label PDF (on success)
`error`	Error message (on failure)
`qrcodeUrl`	QR code URL (if applicable)
`qrcodeError`	QR code error (if applicable)
`shipmentInstruction`	Shipment instructions
`correlationId`	Correlation ID for request tracing
`cancelCutoffTime`	Deadline to cancel this label
`meta`	Additional metadata
`regions`	Other download URLs for the same label file, keyed by region code. See Regional label URLs.

Regional label URLs

regions gives other URLs for the same label file as labelUrl. Use one when the label is downloaded or printed in that region.

Key	Host	Use when
`RHCN`	`label.returnhelperchina.com`	The label is downloaded or printed in mainland China

Each value points to the same PDF as labelUrl. Only the host is different.
Every account gets it. No setup is needed.
Only the labelGenerated event has it. Other label URLs, in API responses and other webhook events, use the labelUrl host only. If you need the regional URL, save it from this event.
regions is {} when labelUrl is null (the label request failed).
Ignore keys you don’t recognise. If the key you need is missing, use labelUrl.

Success example:

{
  "label": {
    "regions": {
      "RHCN": "https://label.returnhelperchina.com/label/202109/example-S210904-0000202.pdf"
    },
    "labelId": 11345,
    "shipmentId": 10825,
    "apiId": 21,
    "refKey": "S210904-0000202",
    "labelRequestStatusCode": "success",
    "serviceType": "usps",
    "trackingNumber": "9201994884299101443342",
    "labelUrl": "https://label.returnhelpercentre.com/label/202109/example-S210904-0000202.pdf",
    "qrcodeUrl": "https://example.com/qrcode.png",
    "qrcodeError": null,
    "error": null,
    "correlationId": null,
    "meta": null
  },
  "category": "labelGenerated",
  "action": "labelGenerated",
  "eventTime": "2021-09-04T17:03:15.8888073Z"
}

Failure example:

{
  "label": {
    "regions": {},
    "labelId": 11352,
    "shipmentId": 10833,
    "apiId": 21,
    "refKey": "S210906-0000085",
    "labelRequestStatusCode": "fail",
    "serviceType": "ap",
    "trackingNumber": null,
    "labelUrl": null,
    "error": "Your combination of suburb, state & postcode doesn't match.",
    "qrcodeUrl": null,
    "qrcodeError": null
  },
  "category": "labelGenerated",
  "action": "labelGenerated",
  "eventTime": "2021-09-06T08:16:33.4674332Z"
}

Warehouse Shipment Arrived (v2)

Sent when a warehouse marks a shipment received. Always followed by one or more Inventory Created events.

This event echoes your sellerReferenceNumber and is the primary reconciliation point between your order records and Return Helper’s identifiers. The V202207 default carries SRN at all three layers in one bundled payload; V202407 carries only the Shipment-layer SRN. See Seller Reference Number for the full reconciliation workflow and version differences.

category: rsl / action: markShipmentArrive / version: 202407 Key fields in shipment:

Field	Description
`shipmentId`	Unique shipment identifier
`returnRequestId`	Linked return request
`trackingNumber`	Carrier tracking number
`sellerReferenceNumber`	Your reference number
`serviceType`	Shipping service used
`customFieldMap`	Custom fields from the original shipment
`shipToWarehouseId`	Receiving warehouse
`receiveDate`	ISO 8601 receive timestamp

{
  "shipment": {
    "shipmentId": "35732",
    "sellerReferenceNumber": "R240725-0000003",
    "returnRequestId": "66848",
    "trackingNumber": "TRACK123456",
    "referenceNumber": "R240725-0000003",
    "serviceType": "fedex",
    "customFieldMap": {
      "customerId": "buyer123"
    },
    "shipToWarehouseId": 2,
    "receiveDate": "2024-07-25T08:53:05.7827073Z"
  },
  "category": "rsl",
  "action": "markShipmentArrive",
  "eventTime": "2024-07-29T05:48:21.381658Z",
  "version": "202407"
}

Inventory Created

Sent after a shipment is received (or a VAS split occurs) to notify that a new return inventory record has been created. One event is sent per inventory item — a single shipment may produce multiple events if multiple packages were received under the same label.

No sellerReferenceNumber in this payload. Neither returnInventory nor shipment carries sellerReferenceNumber; only shipment.referenceNumber is present, and that field echoes the orderNumber you supplied — not the seller reference. If you rely on sellerReferenceNumber to reconcile inventory back to your own records, do not subscribe to newInventoryCreated alone. Pair it with Warehouse Shipment Arrived (carries SRN at all three layers in V202207) or Inventory Handling Complete (carries the Line-Item SRN on returnInventory.sellerReferenceNumber). See Seller Reference Number for the full reconciliation strategy.

category: newInventoryCreated / action: newInventoryCreated Key fields in returnInventory:

Field	Description
`returnInventoryId`	Unique inventory identifier — use this to assign handling
`warehouseId`	Warehouse where inventory is held
`rma`	Warehouse-assigned RMA value
`handlingCode`	Current handling instruction
`handlingStatusCode`	Current handling status
`imageList`	Images captured at receipt
`returnInventoryMetaList`	Additional metadata (e.g. custom fields from shipment)

{
  "returnInventory": {
    "returnInventoryId": "19973",
    "warehouseId": 2,
    "apiId": 21,
    "description": "Item description",
    "quantity": 1,
    "dimension1": 20,
    "dimension2": 20,
    "dimension3": 22,
    "dimensionUom": "cm",
    "weight": 300,
    "weightUom": "g",
    "valueCurrencyCode": "usd",
    "value": 10,
    "handlingCode": "tbc",
    "handlingStatusCode": "pending",
    "completeOn": null,
    "warehouseRemarks": null,
    "handlingUpdatedOn": "2024-07-15T03:29:53.889398",
    "sku": null,
    "rma": "USE-2-240715-D00003-30",
    "imageList": [
      {
        "imageUrl": "https://example.com/image1.jpg",
        "imageKey": "images/returns/202407/image1.jpg"
      }
    ],
    "returnInventoryMetaList": [
      {
        "metaType": "shipmentCustomField",
        "metaMap": {
          "customerId": "buyer123"
        }
      }
    ]
  },
  "shipment": {
    "shipmentId": "9999",
    "returnRequestId": "1234",
    "trackingNumber": "TRACK123456",
    "referenceNumber": "",
    "serviceType": "fedex",
    "customFieldMap": {},
    "shipToWarehouseId": 2,
    "receiveDate": "2024-07-15T03:29:00.000000"
  },
  "category": "newInventoryCreated",
  "action": "newInventoryCreated",
  "eventTime": "2024-07-15T03:30:05.1984163Z",
  "version": "202207"
}

Image Updated

Sent when images are added, changed, or removed for a return inventory line item. category: rrli / action: changeLineItemImage Top-level payload fields:

Field	Type	Description
`imageUrlList`	array of strings	Current image URLs for this line item
`returnRequestLineItem`	object	The affected line item (see below)

Key fields in returnRequestLineItem:

Field	Description
`returnRequestLineItemId`	Line item identifier
`apiId`	Seller API ID
`returnRequestId`	Linked return request ID
`sellerReferenceNumber`	Seller’s reference number
`description`	Item description
`quantity`	Item quantity
`weight` / `weightUom`	Weight and unit
`valueCurrencyCode` / `value`	Value and currency
`handlingCode`	Handling instruction
`isDeleted`	Whether line item is deleted
`rma`	RMA value
`isFraudulent`	Fraud flag
`fraudReasonCode`	Fraud reason code (if flagged)
`customFieldMap`	Custom fields

{
  "imageUrlList": [
    "https://file.returnhelpercentre.com/img/returns/202606/27_1000040536_lmpiohbx.5n3.jpg",
    "https://file.returnhelpercentre.com/images/returns/202603/16209788537041243876_USE-21-260303-P00156-19_..._4290.jpg"
  ],
  "returnRequestLineItem": {
    "returnRequestLineItemId": 10759,
    "apiId": 21,
    "returnRequestId": 9237,
    "returnRequestLineItemNumber": "RL210706-0000020",
    "sellerReferenceNumber": "RL210706-0000020",
    "description": "Item description",
    "quantity": 1,
    "weight": 100.0,
    "weightUom": "g",
    "valueCurrencyCode": "usd",
    "value": 463.0,
    "handlingCode": 0,
    "isDeleted": false
  },
  "category": "rrli",
  "action": "changeLineItemImage",
  "eventTime": "2021-07-06T13:02:24.5575164Z"
}

URLs in imageUrlList are publicly fetchable, do not expire, and are safe to cache client-side. Persist them as-is. Empty state: imageUrlList: [].

Unknown Shipment Assigned

Sent when a shipment with no prior return request is identified and assigned to a seller. category: rsl / action: assignUnknown / version: 202407 Key fields in returnInventory:

Field	Description
`returnInventoryId`	Unique inventory identifier
`warehouseId`	Warehouse where inventory is held
`apiId`	Seller API ID
`description`	Item description
`quantity`	Item quantity
`dimension1` / `dimension2` / `dimension3`	Measured dimensions
`dimensionUom`	Dimension unit of measurement
`weight`	Measured weight
`weightUom`	Weight unit of measurement
`valueCurrencyCode`	Value currency code
`value`	Declared value
`handlingCode`	Current handling instruction
`handlingStatusCode`	Current handling status
`completeOn`	Handling completion timestamp
`warehouseRemarks`	Warehouse remarks
`handlingUpdatedOn`	Last handling update timestamp
`sku`	SKU assigned by seller
`rma`	Warehouse-assigned RMA
`imageList`	Images captured at receipt

Key fields in unknownShipment:

Field	Description
`unknownShipmentId`	Unique unknown shipment identifier
`unknownShipmentNumber`	Unknown shipment reference number
`description`	Description
`unknownShipmentStatusCode`	Current status
`unknownShipmentCountryCode`	Country code
`warehouseId`	Receiving warehouse
`unknownShipmentServiceType`	Shipping service type
`trackingNumber`	Carrier tracking number
`totalWeight` / `totalWeightUom`	Total weight and unit
`dimension1` / `dimension2` / `dimension3`	Measured dimensions
`dimensionUom`	Dimension unit of measurement
`totalValue` / `totalValueCurrency`	Declared value and currency

Recall Status Update

Recall is retiring soon. To send inventory to the Return Helper Hong Kong warehouse, create a consolidate shipping order with destinationType: RH_WAREHOUSE.

Sent when a recall tracking number is updated or pick-up status changes. category: recall / action: recallUpdateStatus recallUpdateTypeStatus values:

Value	Recall Inventory Status	Description
`updateTrackingNumber`	`in-transit`	Tracking number assigned
`readyToPickUp`	`ready-to-pick-up`	Item ready for pick-up
`pickupBySelf`	`picked-up`	Picked up by customer
`pickupByCourier`	`picked-up`	Picked up by local courier
`pickupByOthers`	`picked-up`	Picked up by another party

{
  "recall": {
    "apiId": 103,
    "recallId": 938,
    "recallNumber": "RCL240423-0000001",
    "recallStatusCode": "in-progress",
    "warehouseRemarks": null,
    "recallInventoryList": [
      {
        "recallInventoryId": 1145,
        "returnInventoryId": 18600,
        "recallInventoryStatusCode": "in-transit",
        "pickUpCode": "pending",
        "trackingNumber": "AWB-TRACKING-NUMBER",
        "listName": null,
        "weight": null,
        "amount": null,
        "pickUpOn": null,
        "courierTrackingNumber": null,
        "remarks": null,
        "recallServiceType": "dhl",
        "rma": "USE-1005-240523-D00001-25"
      }
    ]
  },
  "recallUpdateTypeStatus": "updateTrackingNumber",
  "category": "recall",
  "action": "recallUpdateStatus",
  "eventTime": "2024-04-23T07:50:49.2479819Z"
}

Resend Status Update

Sent when a resend tracking number is updated or the resend completes or fails. category: resend / action: updateResendStatus Top-level payload fields:

Field	Type	Description
`resend`	object	Resend order details (see below)
`returnInventoryList`	array	Inventory items being resent
`resendShipmentList`	array	The resend shipment for this resend (see below)

Key fields in resend:

Field	Description
`resendId`	Unique resend order identifier
`apiId`	Seller API ID
`resendNumber`	Resend order number
`resendStatusCode`	Current status: `0` — pending, `1` — canceled, `2` — in progress, `3` — completed, `4` — failed, `5` — queued, `6` — label success
`description`	Order description
`remarks`	Seller remarks
`warehouseRemarks`	Warehouse remarks

Key fields in each resendShipmentList entry:

Field	Description
`resendShipmentId`	Resend shipment identifier
`resendId`	Resend order this shipment belongs to
`resendShipmentNumber`	Resend shipment number
`trackingNumber`	Carrier tracking number (when available)
`sellerReferenceNumber`	Your own reference for this resend
`error`	Error message (when the shipment failed)

resendShipmentList always contains exactly one entry — a resend has one and only one resend shipment. Read it as resendShipmentList[0].

trackingNumber is not a top-level field. It lives on the resend shipment: resendShipmentList[0].trackingNumber.

Check resend.resendStatusCode:

3 — completed (read resendShipmentList[0].trackingNumber)
4 — failed (read resendShipmentList[0].error)

{
  "resend": {
    "resendId": 2902,
    "apiId": 21,
    "resendNumber": "RSD221003-0000001",
    "resendStatusCode": 3
  },
  "returnInventoryList": [
    {
      "returnInventoryId": 14129,
      "rma": "SGP240101-0000001"
    }
  ],
  "resendShipmentList": [
    {
      "resendShipmentId": 2897,
      "resendId": 2902,
      "resendShipmentNumber": "RSDS221003-0000001",
      "trackingNumber": "9201994884299101443342",
      "sellerReferenceNumber": "ORDER-0001",
      "error": null
    }
  ],
  "category": "resend",
  "action": "updateResendStatus"
}

Use resendShipmentList[0].sellerReferenceNumber to match the event to your own order record without storing Return Helper’s resendId.

sellerReferenceNumber only carries a value when the resend was created by an Enterprise account through Create resend by SKU with a reference supplied. It is null for every other resend. To look a resend up on demand by this value, use Search resend by seller reference number.

VAS Update

Sent when a value-added service completes. category: rrliv / action: vasUpdated Each item in updateVasList:

Field	Description
`returnRequestLineItemVasId`	VAS record identifier
`vasResult`	VAS result description
`weight` / `weightUom`	Weight and unit after VAS
`dimension1` / `dimension2` / `dimension3`	Dimensions after VAS
`dimensionUom`	Dimension unit of measurement
`vasStatusCode`	VAS status code
`imageUrlList`	VAS result images

{
  "updateVasList": [
    {
      "returnRequestLineItemVasId": 65205,
      "vasResult": "VAS result details",
      "weight": 1000.0,
      "weightUom": "g",
      "dimension1": 25.0,
      "dimension2": 20.0,
      "dimension3": 10.0,
      "dimensionUom": "cm",
      "vasStatusCode": "SUCCESSFUL",
      "imageUrlList": [
        "https://file.returnhelpercentre.com/img/returns/202606/27_1000011051_eu4jjyfj.wth.jpg",
        "https://file.returnhelpercentre.com/img/returns/202606/27_1000011050_0nfetxuv.5hb.jpg"
      ]
    }
  ],
  "category": "rrliv",
  "action": "vasUpdated",
  "eventTime": "2021-07-06T12:15:55.9038524Z"
}

URLs in imageUrlList are publicly fetchable, do not expire, and are safe to cache client-side. Persist them as-is. Empty state: imageUrlList: [] (some VAS types do not produce photos; the entry remains in updateVasList[] with an empty array).

Inventory Handling Complete

Sent when a handling instruction (dispose, resend, recall, etc.) is completed by the warehouse. category: rinv / action: completeInventoryHandling Key fields in returnInventory:

Field	Description
`returnInventoryId`	Unique inventory identifier
`warehouseId`	Warehouse where inventory is held
`returnRequestLineItemId`	Linked line item ID
`apiId`	Seller API ID
`returnRequestId`	Linked return request ID
`sellerReferenceNumber`	Seller’s reference number
`description`	Item description
`quantity`	Item quantity
`dimension1` / `dimension2` / `dimension3`	Measured dimensions
`dimensionUom`	Dimension unit of measurement
`weight`	Measured weight
`weightUom`	Weight unit of measurement
`valueCurrencyCode`	Value currency code
`value`	Declared value
`handlingCode`	Handling instruction (see table below)
`handlingStatusCode`	Handling status (see table below)
`completeBy`	User who completed handling
`completeOn`	Completion timestamp
`warehouseRemarks`	Warehouse remarks
`handlingUpdatedOn`	Last handling update timestamp
`stopAgingOn`	Aging stop timestamp
`sku`	SKU assigned by seller
`rma`	Warehouse-assigned RMA
`returnInventoryMetaList`	Additional metadata list

handlingCode values:

ID	Code	Description
0	`tbc`	To Be Confirmed
1	`rtn`	Recall
2	`dis`	Disposal
3	`rsd`	Resend
4	`ohd`	On Hold
5	`oth`	Others

handlingStatusCode values:

ID	Code	Description
0	`pending`	Pending
1	`inProgress`	In Progress
2	`completed`	Completed

Inventory Recalibrated

Sent when a warehouse updates the measured dimensions or weight of a return inventory. category: completeRecalibrate / action: completeRecalibrate Key fields in recalibrateSupplement:

Field	Description
`warehouseId`	Warehouse that performed recalibration
`returnInventoryId`	Affected inventory ID
`returnRequestLineItemId`	Linked line item ID
`rma`	RMA value
`dimension1` / `dimension2` / `dimension3`	Updated dimensions
`weight`	Updated weight
`recalibratedOn`	Recalibration timestamp
`returnInventoryMetaList`	Updated metadata list (each entry has `metaType` and `metaMap`)

{
  "recalibrateSupplement": {
    "warehouseId": 8,
    "returnInventoryId": 18191,
    "returnRequestLineItemId": 38320,
    "rma": "USE-1005-240523-D00001-25",
    "dimension1": 20.0,
    "dimension2": 20.0,
    "dimension3": 20.0,
    "weight": 310.0,
    "recalibratedOn": "2024-04-04T00:42:11.1325135Z"
  },
  "category": "completeRecalibrate",
  "action": "completeRecalibrate",
  "eventTime": "2024-04-04T00:54:29.4337417Z"
}

Inventory Meta Updated

Sent when a warehouse or user adds or updates metadata on a return inventory. category: updateReturnInventoryMeta / action: updateReturnInventoryMeta The payload contains returnInventory with the same structure as Inventory Created, including the updated returnInventoryMetaList. metaType values:

usr — user-supplied meta
whs — warehouse-supplied meta

RMA Updated

Sent when a warehouse corrects an incorrect RMA assignment. category: notifyUserRmaSwapped / action: notifyUserRmaSwapped Key fields in payload:

Field	Description
`userApiId`	Seller API ID
`clientCode`	Client code
`returnInventoryId`	Affected inventory ID
`oldRma`	Previous RMA value
`newRma`	New corrected RMA value

{
  "payload": {
    "userApiId": 21,
    "clientCode": "RH21",
    "returnInventoryId": "19029",
    "oldRma": "USE-2-240517-D00026-56",
    "newRma": "USE-2-240520-D00001-35"
  },
  "category": "notifyUserRmaSwapped",
  "action": "notifyUserRmaSwapped",
  "eventTime": "2024-05-23T06:26:43.4416977Z"
}

SKU Updated

Sent when a seller updates the SKU of a return inventory. category: userUpdateReturnInventorySku / action: userUpdateReturnInventorySku The payload contains returnRequest and returnInventory. Key fields in returnRequest:

Field	Description
`returnRequestId`	Unique return request identifier
`apiId`	Seller API ID
`sellerReferenceNumber`	Seller’s reference number
`returnStatusCode`	Return request status
`returnTitle`	Return title
`totalValue` / `totalValueCurrency`	Total declared value and currency
`remarks`	Remarks
`rma`	RMA value
`isArchived`	Whether the request is archived
`returnRequestSourceType`	Source type of the return request

The returnInventory object follows the same structure as Inventory Handling Complete, with the updated sku field.

Split Line Item

Sent when a VAS operation splits a parcel into multiple inventories. Contains the new line item and inventory records for each resulting parcel. category: lineItemVasReturnInventoryLineItem / action: splitLineItem Top-level payload fields:

Field	Type	Description
`returnRequestId`	integer	Linked return request ID
`returnRequestLineItemId`	long	Original line item ID
`returnRequestLineItemVasId`	long	VAS record ID that triggered the split
`vasStatusCode`	string	VAS status code
`splitLineItemAndReturnInventoryList`	array	List of resulting split items (see below)

Each item in splitLineItemAndReturnInventoryList contains:

Field	Type	Description
`returnRequestLineItem`	object	New line item record (includes `returnRequestLineItemId`, `sellerReferenceNumber`, `description`, `quantity`, `weight`, `weightUom`, `valueCurrencyCode`, `value`, `handlingCode`, `rma`, `customFieldMap`)
`returnInventory`	object	New inventory record (same structure as Inventory Handling Complete)
`returnRequestLineItemSupplement`	object	Supplement with dimensions and weight for the new line item

Warehouse Remarks Updated

Sent when a warehouse updates remarks on a return request. category: warehouseUpdateWarehouseRemarks / action: warehouseUpdateWarehouseRemarks The payload contains three objects:

returnRequest — the return request (same structure as SKU Updated → returnRequest)
shipment — the shipment record with full address details, dimensions, weight, cost, and customFieldMap
returnInventory — the affected inventory (same structure as Inventory Handling Complete), with the updated warehouseRemarks field

Buyer Return Label Generated

Sent when a buyer creates a return in the Branded Return portal and a label is generated.

Only applicable to customers integrated with the Return Helper Branded Return service.

category: buyerReturnRrLabel / action: buyerReturnLabelGenerated Check buyerReturn.labelRequestStatusCode for "success" or "fail". Key fields in buyerReturn:

Field	Description
`buyerReturnId`	Unique buyer return identifier
`apiId`	Seller API ID
`sellerReferenceNumber`	Seller’s reference number
`returnRequestId`	Linked return request ID (if created)
`shipmentId`	Linked shipment ID (if created)
`returnRequestNumber`	Return request number
`shipmentNumber`	Shipment number
`totalValue` / `totalValueCurrency`	Declared value and currency
`remarks`	Remarks
`labelId`	Label ID
`labelRequestStatusCode`	`"success"` or `"fail"`
`trackingNumber`	Tracking number (on success)
`labelFile`	Object with `labelUrl` and `labelKey`
`shipmentInstruction`	Shipment instructions
`error`	Error message (on failure)
`warehouseId`	Destination warehouse
`shipmentServiceType`	Shipping service type
`shipmentCountryCode`	Shipment country
`shipmentName` / `shipmentPhone` / `shipmentEmail`	Contact details
`shipmentStreet1` / `shipmentStreet2` / `shipmentStreet3`	Address lines
`shipmentCity` / `shipmentState` / `shipmentPostalCode`	Address details
`costCurrencyCode` / `cost`	Shipping cost
`sellerCostCurrencyCode` / `sellerCost`	Seller cost
`buyerCostCurrencyCode` / `buyerCost`	Buyer cost
`boxType`	Box type
`weight` / `weightUom`	Weight and unit
`dimension1` / `dimension2` / `dimension3` / `dimensionUom`	Parcel dimensions
`customFieldMap`	Custom fields
`buyerReturnLineItemList`	List of line items (see below)

Each item in buyerReturnLineItemList:

Field	Description
`buyerReturnLineItemId`	Line item ID
`sellerReferenceNumber`	Seller’s reference
`description`	Item description
`quantity`	Quantity
`weight` / `weightUom`	Weight and unit
`value` / `valueCurrencyCode`	Value and currency
`returnReasonCode` / `returnReason`	Buyer-selected return reason
`customFieldMap`	Custom fields

Shopify Buyer Return Created

Sent when a buyer creates a return request via Shopify integration. category: shopifyBuyerCreateReturn / action: shopifyBuyerCreateReturn Key fields in shopifyReturn:

Field	Description
`shopifyReturnId`	Unique Shopify return identifier
`apiId`	Seller API ID
`referenceNumber`	Reference number
`returnRequestId`	Linked return request ID (if created)
`shipmentId`	Linked shipment ID (if created)
`returnRequestNumber` / `shipmentNumber`	Return and shipment numbers
`totalValue` / `totalValueCurrency`	Declared value and currency
`remarks`	Remarks
`labelRequestStatusCode`	Label status: `"success"` or `"fail"`
`trackingNumber`	Tracking number (on success)
`labelUrl`	Label URL (on success)
`error`	Error message (on failure)
`warehouseId`	Destination warehouse
`shipmentServiceType` / `shipmentCountryCode`	Shipping service and country
`shipmentName` / `shipmentPhone` / `shipmentEmail`	Contact details
`shipmentStreet1` / `shipmentStreet2` / `shipmentStreet3`	Address lines
`shipmentCity` / `shipmentState` / `shipmentPostalCode`	Address details
`costCurrencyCode` / `cost`	Shipping cost
`boxType`	Box type
`weight` / `weightUom`	Weight and unit
`dimension1` / `dimension2` / `dimension3` / `dimensionUom`	Parcel dimensions
`shopifyShopId`	Shopify shop identifier
`shopifyOrderId` / `shopifyOrderNumber` / `shopifyOrderName`	Shopify order details
`shopifyReturnStatusCode`	Shopify return status
`requestParty`	Party who initiated the return
`customFieldMap`	Custom fields

Each item in shopifyReturnLineItemList:

Field	Description
`shopifyReturnLineItemId`	Line item ID
`sellerReferenceNumber`	Seller’s reference
`description`	Item description
`quantity`	Quantity
`sku`	Product SKU
`weight` / `weightUom`	Weight and unit
`value` / `valueCurrencyCode`	Value and currency
`returnReasonCode` / `returnReason`	Buyer-selected return reason
`shopifyProductId`	Shopify product ID
`buyerNotes`	Buyer’s notes
`customFieldMap`	Custom fields

Consolidate Shipping Cost Updated

Sent when the shipping cost of a consolidated shipping order is updated. category: consolidateShippingOrderShippingFeeUpdated / action: consolidateShippingOrderShippingFeeUpdated Key fields in order:

Field	Description
`consolidateShippingOrderId`	Order identifier
`consolidateShippingOrderNumber`	Order number
`consolidateShippingOrderStatus`	Current status
`outboundWarehouseId`	Outbound warehouse
`shippingMethod`	Always `null`
`shippingFee` / `currencyCode`	Updated shipping fee and currency
`shipToContactName` / `shipToPhone` / `shipToEmail`	Ship-to contact
`shipToCompanyName`	Ship-to company
`shipToStreet1` / `shipToStreet2` / `shipToStreet3`	Ship-to address lines
`shipToCity` / `shipToState` / `shipToPostalCode` / `shipToCountry`	Ship-to address
`deliveryInstructions`	Delivery instructions

Consolidate Shipping All Packed

Sent when a warehouse has packed all inventories into boxes for a consolidated order. category: consolidateShippingOrderInventoryAllPacked / action: consolidateShippingOrderInventoryAllPacked Key fields in order:

Field	Description
`consolidateShippingOrderId`	Order identifier
`consolidateShippingOrderNumber`	Order number
`consolidateShippingOrderStatus`	Current status
`outboundWarehouseId`	Outbound warehouse
`shippingFee` / `currencyCode`	Shipping fee and currency
`shippingMethod`	Always `null`
`customFieldMap`	Custom fields
`deliveryInstructions`	Delivery instructions
`shipmentList`	List of shipments (see below)

Each item in shipmentList:

Field	Description
`consolidateShippingShipmentId`	Shipment identifier
`consolidateShippingShipmentNumber`	Shipment number
`consolidateShippingShipmentStatus`	Shipment status
`boxList`	List of boxes in this shipment

Each item in boxList:

Field	Description
`consolidateShippingShipmentBoxId`	Box identifier
`boxNumber`	Box number
`consolidateShippingShipmentBoxStatus`	Box status
`consolidateShippingInventoryList`	Inventories in this box

Each item in consolidateShippingInventoryList:

Field	Description
`consolidateShippingInventoryId`	Line identifier
`itemType`	`RMA` or `FNSKU`
`returnInventoryId` / `rma`	`RMA` lines only, otherwise `null`
`fnsku`	`FNSKU` lines only, otherwise `null`
`quantity`	Pieces of this line in the box. Always `1` for `RMA` lines.
`consolidateShippingInventoryStatus`	Line status

A box can hold RMA lines, FNSKU lines or both. A box with no RMA lines is still listed.

Consolidate Shipment Sent

Sent when a warehouse dispatches a consolidated shipment to a carrier. category: consolidateShippingShipmentSent / action: consolidateShippingShipmentSent Key fields in shipment:

Field	Description
`consolidateShippingShipmentId`	Shipment identifier
`consolidateShippingShipmentNumber`	Shipment number
`consolidateShippingShipmentStatus`	Current status
`awb`	Air Waybill number
`serviceProvider`	Carrier service provider
`shipDate`	Ship date
`boxList`	List of boxes (same structure as All Packed → boxList)
`consolidateShippingOrderId`	Parent order identifier
`consolidateShippingOrderNumber`	Parent order number
`consolidateShippingOrderStatus`	Parent order status
`outboundWarehouseId`	Outbound warehouse
`customFieldMap`	Custom fields

Consolidate Shipping AWB Updated

Sent when the Air Waybill number for a consolidated shipment is updated. category: consolidateShippingShipmentShipped / action: consolidateShippingShipmentShipped The shipment object follows the same structure as Consolidate Shipment Sent, with the updated awb field. For RH_WAREHOUSE orders, this event is sent when the warehouse records the AWB. consolidateShippingShipmentStatus is IN_TRANSIT, and nothing is charged yet: the shipment is charged when it arrives, reported by Consolidate shipment arrived.

Consolidate Shipment Arrived

Sent once per shipment of an RH_WAREHOUSE order, when the shipment arrives at the Return Helper warehouse and its shipping fee is charged. category: consolidateShippingShipmentArrived / action: consolidateShippingShipmentArrived / version: 202609

Version 202609 is opt-in. Contact Return Helper customer service to receive it.

Field	Description
`order`	The order. `order.shipmentList` holds only the shipment that arrived.
`arrivedShipmentCount`	Shipments of this order that hold items and have arrived, including this one
`totalShipmentCount`	Shipments of this order that hold items. Empty shipments are not counted.

An order with three shipments holding items sends three events: 1/3, 2/3, 3/3. Fields in order:

Field	Description
`consolidateShippingOrderId` / `consolidateShippingOrderNumber`	Order identifiers
`apiId`	Your account ID
`consolidateShippingOrderStatus`	Order status
`outboundWarehouseId`	Warehouse the goods left from
`destinationType`	`RH_WAREHOUSE`
`destinationWarehouseId`	Destination warehouse
`shippingFee` / `currencyCode`	Order shipping fee so far
`customFieldMap` / `deliveryInstructions`	As set on the order
`shipmentList`	The arrived shipment (see below)

shippingMethod is not in version 202609. Each item in shipmentList:

Field	Description
`consolidateShippingShipmentId` / `consolidateShippingShipmentNumber`	Shipment identifiers
`consolidateShippingShipmentStatus`	`READY_TO_PICKUP`
`awb`	Air Waybill number
`chargeableWeight`	Chargeable weight in grams
`boxList`	Boxes in this shipment, each with `consolidateShippingShipmentBoxId`, `boxNumber`, `consolidateShippingShipmentBoxStatus` and `consolidateShippingInventoryList`

Each item in consolidateShippingInventoryList:

Field	Description
`consolidateShippingInventoryId`	Line identifier
`itemType`	`RMA` or `FNSKU`
`returnInventoryId` / `rma`	`RMA` lines only, otherwise `null`
`fnsku`	`FNSKU` lines only, otherwise `null`
`quantity`	Pieces in this box
`consolidateShippingInventoryStatus`	Line status

{
  "category": "consolidateShippingShipmentArrived",
  "action": "consolidateShippingShipmentArrived",
  "eventTime": "2026-10-05T03:12:45Z",
  "version": "202609",
  "notificationId": "01K6X2M8Q4R7T9V1W3Y5Z7B9C1",
  "order": {
    "consolidateShippingOrderId": "01K6RA4F7H9J2K5M8N1P3Q6S8T",
    "consolidateShippingOrderNumber": "CNS260928-0000123",
    "apiId": 12345,
    "consolidateShippingOrderStatus": "PARTIALLY_SHIPPED",
    "outboundWarehouseId": 101,
    "destinationType": "RH_WAREHOUSE",
    "destinationWarehouseId": 1,
    "shippingFee": 27.0,
    "currencyCode": "usd",
    "customFieldMap": {},
    "deliveryInstructions": null,
    "shipmentList": [
      {
        "consolidateShippingShipmentId": "01K6T1B3D5F7H9K2M4P6R8T0V2",
        "consolidateShippingShipmentNumber": "CNSS260930-0000045",
        "consolidateShippingShipmentStatus": "READY_TO_PICKUP",
        "awb": "TRACK123456789",
        "chargeableWeight": 2400,
        "boxList": [
          {
            "consolidateShippingShipmentId": "01K6T1B3D5F7H9K2M4P6R8T0V2",
            "consolidateShippingShipmentBoxId": "01K6T1C4E6G8J1L3N5Q7S9U1W3",
            "boxNumber": "1",
            "consolidateShippingShipmentBoxStatus": "SHIPPED",
            "consolidateShippingInventoryList": [
              {
                "consolidateShippingShipmentBoxId": "01K6T1C4E6G8J1L3N5Q7S9U1W3",
                "consolidateShippingInventoryId": "01K6RB2C4E6G8J1L3N5Q7S9U1W",
                "itemType": "RMA",
                "returnInventoryId": 987654,
                "rma": "USE-2-260915-D00003-30",
                "fnsku": null,
                "quantity": 1,
                "consolidateShippingInventoryStatus": "SHIPPED"
              },
              {
                "consolidateShippingShipmentBoxId": "01K6T1C4E6G8J1L3N5Q7S9U1W3",
                "consolidateShippingInventoryId": "01K6RB3D5F7H9K2M4P6R8T0V2X",
                "itemType": "FNSKU",
                "returnInventoryId": null,
                "rma": null,
                "fnsku": "X00EXAMPLE1",
                "quantity": 6,
                "consolidateShippingInventoryStatus": "SHIPPED"
              }
            ]
          }
        ]
      }
    ]
  },
  "arrivedShipmentCount": 1,
  "totalShipmentCount": 2
}

Consolidate Order Completed

Sent when every item in a consolidated order has shipped. For RH_WAREHOUSE orders, every shipment holding items must also have arrived; the event follows the order’s last Consolidate shipment arrived. category: consolidateShippingOrderCompleted / action: consolidateShippingOrderCompleted The order object follows the same structure as Consolidate Shipping All Packed, including the full shipmentList with boxList and inventory details.

Consolidate Order Cancelled

Sent when a warehouse force-cancels a consolidated shipping order. category: consolidateShippingOrderCancelled / action: consolidateShippingOrderCancelled Key fields in order:

Field	Description
`consolidateShippingOrderId`	Order identifier
`consolidateShippingOrderNumber`	Order number
`consolidateShippingOrderStatus`	`CANCELED`
`outboundWarehouseId`	Outbound warehouse
`shippingMethod`	Always `null`
`shippingFee`	Shipping fee
`deliveryInstructions`	Delivery instructions
`customFieldMap`	Custom fields

Transaction Added

Sent once for every transaction posted to your account: charges, refunds, recharges, and top-ups.

apiTransaction.notes usually describes the action the transaction refers to, so you don’t need to resolve headId to understand a transaction.

category: transaction / action: addTransaction / version: 202610 Key fields in apiTransaction:

Field	Type	Description
`apiTransactionId`	long	Transaction identifier
`transactionNumber`	string	Transaction number, for example `T2600012345`. Unique per transaction.
`apiId`	long	Your API account ID
`currencyCode`	string	Currency code, lowercase (for example `usd`)
`transactionType`	string	Transaction type code. See What headId refers to.
`headId`	string	ID of the record the transaction was booked against. Depends on `transactionType`; see What headId refers to.
`amount`	number	Signed amount. Negative is a charge; positive is a refund or top-up.
`notes`	string	Human-readable description. Wording may change; do not parse.
`createOn`	string	When the transaction was posted (UTC, ISO 8601)
`createBy`	string

Key fields in apiBalance:

Field	Type	Description
`apiBalanceId`	long	Balance record identifier
`apiId`	long	Your API account ID
`currencyCode`	string	Currency code, lowercase
`balance`	number	Your balance in `currencyCode` right after this transaction was posted

balance is the value when this transaction was posted, not your current balance. Events can arrive out of order. For the current figure, call Get API account balance.

{
  "apiTransaction": {
    "apiTransactionId": 100245,
    "transactionNumber": "T2600012345",
    "apiId": 21,
    "currencyCode": "usd",
    "transactionType": "csl",
    "headId": "11345",
    "amount": -12.960,
    "notes": "charge for shipment:30385",
    "createOn": "2026-10-12T03:29:11.180251",
    "createBy": "21"
  },
  "apiBalance": {
    "apiBalanceId": 7,
    "apiId": 21,
    "currencyCode": "usd",
    "balance": 1520.350
  },
  "category": "transaction",
  "action": "addTransaction",
  "eventTime": "2026-10-12T03:29:11.2396605Z",
  "version": "202610",
  "notificationId": "01J8HV4X54S8AV4FY0SJKVM7QW"
}

What headId refers to

headId is the ID of the record a transaction was booked against. Which ID it holds depends on transactionType. headId is always a string. A refund or recharge has the same headId as the charge it adjusts.

`headId` is	Where you get this ID
Your `apiId`	`RETURNHELPER-API-ID` header, or Get API account information
`labelId`	`label.labelId` in Label result
`returnRequestId`	Buyer return label generated, Shopify buyer return created
`returnInventoryId`	Inventory created, Warehouse shipment arrived (v2)
`returnRequestLineItemVasId`	VAS update
`resendId`	Create resend order response, Resend status update
Resend inventory record ID	Not returned by any API response or webhook
`fbaInstructionId`	Create FBA instructions response
`fbaShipmentId`	Create FBA shipment response
`consolidateShippingShipmentBoxId`	`boxList` in Consolidate shipping all packed
`consolidateShippingInventoryId`	`consolidateShippingInventoryList` in Consolidate shipping all packed
`consolidateShippingShipmentId`	Consolidate shipment sent

Every transactionType, what it is for, and which ID its headId holds:

`transactionType`	Description	`headId` is
`chr`	General charge type	Your `apiId`
`top`	Top up	Your `apiId`
`acs`	Auto Charge Storage fee	Your `apiId`
`acf`	Auto Charge FBA Inventory Storage Fee	Your `apiId`
`rtp`	Auto Charge for Recall ready to pick	Your `apiId`
`csl`	Shipment charge (system charge user when create label)	`labelId`
`rsl`	Shipment charge refund if create label fail	`labelId` or `returnRequestId`¹
`rcl`	Refund for canceled shipment label by user	`labelId`
`RECHARGE_SHIPPING_LABEL`	Recharge for cancel shipment label	`labelId`
`bps`	Buyer portal shipment cost (total)	`returnRequestId`
`brt`	Buyer payment for buyer return	`returnRequestId`
`sps`	Shopify Return Shipment Cost	`returnRequestId`
`REFUND_CANCEL_BUYER_RETURN_LABEL`	Refund for Cancel Buyer return Label	`returnRequestId`
`REFUND_CANCEL_SHOPIFY_RETURN_LABEL`	Refund for Cancel Shopify Return Label	`returnRequestId`
`bbc`	Bounce back warehouse handling fee	`returnInventoryId`
`brc`	Buyer return warehouse handling fee	`returnInventoryId`
`fbr`	FBA restock warehouse handling fee	`returnInventoryId`
`cup`	Claim unknown parcel warehouse handling fee	`returnInventoryId`
`dis`	Dispose handling fee	`returnInventoryId`
`soh`	Splitting Outbound Handling Fee	`returnInventoryId`
`swh`	Splitting Warehouse Handling Fee	`returnInventoryId`
`CANCELED_LABEL_ARRIVED`	Canceled label warehouse handling fee	`returnInventoryId`
`CANCELED_LABEL_PENALTY`	Penalty for canceled label reuse	`returnInventoryId`
`CONSOLIDATE_SHIPPING_OUTBOUND`	Charge for consolidate shipping outbound handling fee	`returnInventoryId`
`REFUND_CLAIM_UNKNOWN`	Refund for Claim unknown parcel warehouse handling fee	`returnInventoryId`
`RECHARGE_CLAIM_UNKNOWN`	Recharge for Claim unknown parcel warehouse handling fee	`returnInventoryId`
`REFUND_BUYER_RETURN`	Refund for Buyer return parcel warehouse handling fee	`returnInventoryId`
`RECHARGE_BUYER_RETURN`	Recharge for Buyer return parcel warehouse handling fee	`returnInventoryId`
`REFUND_BOUNCE_BACK`	Refund for Bounce back warehouse handling fee	`returnInventoryId`
`RECHARGE_BOUNCE_BACK`	Recharge for Bounce back warehouse handling fee	`returnInventoryId`
`REFUND_FBA_RESTOCK`	Refund for FBA restock warehouse handling fee	`returnInventoryId`
`RECHARGE_FBA_RESTOCK`	Recharge for FBA restock warehouse handling fee	`returnInventoryId`
`REFUND_CANCELED_LABEL_ARRIVED`	Refund for Canceled label warehouse handling fee	`returnInventoryId`
`RECHARGE_CANCELED_LABEL_ARRIVED`	Recharge for canceled label warehouse handling fee	`returnInventoryId`
`REFUND_CANCELED_LABEL_PENALTY`	Refund for penalty for canceled label reuse	`returnInventoryId`
`RECHARGE_CANCELED_LABEL_PENALTY`	Recharge for penalty for canceled label reuse	`returnInventoryId`
`rpk`	Charge Vas Repack	`returnRequestLineItemVasId`
`tpc`	Charge Vas Take Picture	`returnRequestLineItemVasId`
`pin`	Product inspection warehouse handling fee	`returnRequestLineItemVasId`
`rmh`	Warehouse merge resend parcel handling fee	`resendId`
`rlr`	Shipment Charge Base on Resend Label Request	`resendId`
`rsh`	Buyer resend warehouse handling fee	Resend inventory record ID
`fbd`	FBA Dispose warehouse handling fee	`fbaInstructionId`
`frh`	FBA relabel handling fee	`fbaInstructionId`
`fih`	FBA inbound warehouse handling fee	`fbaShipmentId`
`fch`	FNSKU counting handling fee	`fbaShipmentId`
`CONSOLIDATE_SHIPPING_MERGE`	Charge for consolidate shipping merge handling fee	`consolidateShippingShipmentBoxId`
`CONSOLIDATE_SHIPPING_OUTBOUND_FNSKU`	Consolidate shipping outbound handling fee for FNSKU	`consolidateShippingInventoryId`
`CONSOLIDATE_SHIPPING_SHIPMENT`	Charge for consolidate shipping shipment fee	`consolidateShippingShipmentId`

¹ rsl refunds a label that failed. headId is the labelId, or the returnRequestId when the failed label was a buyer return label.

Every transaction is sent; you can’t subscribe to individual types. Branch on transactionType and the sign of amount.
New transactionType values may be added. For a type you don’t recognise, still record amount and balance; don’t reject the event.
A shipment can have more than one label, so it can have more than one csl. Use Label result to map labelId to shipmentId.
createOn is when the transaction was posted; eventTime is when the notification was sent.

​Overview

​Setting Up Your Webhook Endpoint

​Endpoint Requirements

​Registering Your Endpoint

​Event Delivery

​Notification Headers

​Legacy headers

​Signature Verification

​Worked Example

​Step-by-Step Verification

​Sample Code

​Retry Mechanism

​Common Body Fields

​Notification Event Reference

​Notification Payloads

​Label Result

​Regional label URLs

​Warehouse Shipment Arrived (v2)

​Inventory Created

​Image Updated

​Unknown Shipment Assigned

​Recall Status Update

​Resend Status Update

​VAS Update

​Inventory Handling Complete

​Inventory Recalibrated

​Inventory Meta Updated

​RMA Updated

​SKU Updated

​Split Line Item

​Warehouse Remarks Updated

​Buyer Return Label Generated

​Shopify Buyer Return Created

​Consolidate Shipping Cost Updated

​Consolidate Shipping All Packed

​Consolidate Shipment Sent

​Consolidate Shipping AWB Updated

​Consolidate Shipment Arrived

​Consolidate Order Completed

​Consolidate Order Cancelled

​Transaction Added

​What headId refers to

Overview

Setting Up Your Webhook Endpoint

Endpoint Requirements

Registering Your Endpoint

Event Delivery

Notification Headers

Legacy headers

Signature Verification

Worked Example

Step-by-Step Verification

Sample Code

Retry Mechanism

Common Body Fields

Notification Event Reference

Notification Payloads

Label Result

Regional label URLs

Warehouse Shipment Arrived (v2)

Inventory Created

Image Updated

Unknown Shipment Assigned

Recall Status Update

Resend Status Update

VAS Update

Inventory Handling Complete

Inventory Recalibrated

Inventory Meta Updated

RMA Updated

SKU Updated

Split Line Item

Warehouse Remarks Updated

Buyer Return Label Generated

Shopify Buyer Return Created

Consolidate Shipping Cost Updated

Consolidate Shipping All Packed

Consolidate Shipment Sent

Consolidate Shipping AWB Updated

Consolidate Shipment Arrived

Consolidate Order Completed

Consolidate Order Cancelled

Transaction Added

What headId refers to