> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.returnhelper.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks & Notifications

> Receiving asynchronous event notifications from Return Helper

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

## Setting Up Your Webhook Endpoint

### Endpoint Requirements

Before submitting a setup request, make sure your endpoint 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 HTTP 200** — your server must return a `200 OK` 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

### Registering Your Endpoint

To register your webhook endpoint, please fill in the [Webhook Setup Request Form](https://forms.gle/iBVkRZvfLQ8o1Nqg8). The form contains all the information we need to complete the setup quickly, and is the fastest way to get your endpoint activated.

<Note>
  We recommend using the form above, as it ensures all required details are captured in one step. If you are unable to use the form, you may also send the request by email — see the template below.
</Note>

<Accordion title="Email template (if you cannot use the form)">
  If you prefer to contact us by email, send the following to [support@returnhelper.com](mailto:support@returnhelper.com):

  ```
  Subject: Request webhook setup in Return Helper - <YOUR CLIENT CODE>

  To: support@returnhelper.com

  Dear Support Team,

  We would like to request webhook setup in Return Helper. Please find the details below:

  Email address: <YOUR EMAIL ADDRESS>
  Client code:   <YOUR CLIENT CODE>
  Endpoint:      https://your-server.example.com/webhook
  Environment:   <Sandbox / Production / Both>
  Comments:      <Any additional information, or leave blank>
  ```
</Accordion>

## 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](#signature-verification). |
| `RETURNHELPER-API-ID`       | string | The `apiId` of the account the notification belongs to. Retrieve yours with [Get API account information](/api-reference/account/get-api-info).     |
| `RETURNHELPER-API-NAME`     | string | The `apiName` of that account.                                                                                                                      |
| `ReturnHelper-Signature`    | string | HMAC-SHA256 signature for verification — see [Signature Verification](#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.                              |

<Note>
  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.
</Note>

## Signature Verification

<Warning>
  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.
</Warning>

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](/introduction#authentication) — or read it programmatically with [Get signing key](/api-reference/apiaccount/get-signing-key).

### Worked Example

Given the following incoming request:

**Headers:**

```json theme={null}
{
  "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):

1. HTTP method: `POST`
2. Your notification endpoint URL: `https://s2024-01-12.free.beeceptor.com`
3. The `RETURNHELPER-TRIGGERED-AT` value from Step 2
4. 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:

1. Decode the `string_to_sign` (from Step 3) from Base64 → byte array
2. Decode your signing key from Base64 → byte array
3. Compute HMAC-SHA256 using the signing key bytes over the `string_to_sign` bytes → signature byte array
4. 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

<CodeGroup>
  ```java Java theme={null}
  // 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);
    }
  }
  ```

  ```javascript Node.js theme={null}
  // 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);
  ```

  ```typescript TypeScript theme={null}
  // 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();
  ```

  ```apex Apex (Salesforce) theme={null}
  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);
      }
  }
  ```
</CodeGroup>

## 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](#label-result)                                           | `labelGenerated`                             | `labelGenerated`                             | Label generation result (success or failure)     |
| [Warehouse shipment arrived (v2)](#warehouse-shipment-arrived-v2)       | `rsl`                                        | `markShipmentArrive`                         | Shipment received at warehouse (current version) |
| [Inventory created](#inventory-created)                                 | `newInventoryCreated`                        | `newInventoryCreated`                        | New return inventory created                     |
| [Image updated](#image-updated)                                         | `rrli`                                       | `changeLineItemImage`                        | Line item image added, changed, or removed       |
| [Unknown shipment assigned](#unknown-shipment-assigned)                 | `rsl`                                        | `assignUnknown`                              | Unknown shipment assigned to seller              |
| [Recall status update](#recall-status-update)                           | `recall`                                     | `recallUpdateStatus`                         | Recall tracking or pick-up status changed        |
| [Resend status update](#resend-status-update)                           | `resend`                                     | `updateResendStatus`                         | Resend tracking or status changed                |
| [VAS update](#vas-update)                                               | `rrliv`                                      | `vasUpdated`                                 | Value-added service completed or updated         |
| [Inventory handling complete](#inventory-handling-complete)             | `rinv`                                       | `completeInventoryHandling`                  | Handling instruction completed                   |
| [Inventory recalibrated](#inventory-recalibrated)                       | `completeRecalibrate`                        | `completeRecalibrate`                        | Warehouse updated inventory dimensions/weight    |
| [Inventory meta updated](#inventory-meta-updated)                       | `updateReturnInventoryMeta`                  | `updateReturnInventoryMeta`                  | Warehouse or user added/updated meta data        |
| [RMA updated](#rma-updated)                                             | `notifyUserRmaSwapped`                       | `notifyUserRmaSwapped`                       | Warehouse corrected an RMA assignment            |
| [SKU updated](#sku-updated)                                             | `userUpdateReturnInventorySku`               | `userUpdateReturnInventorySku`               | Seller updated inventory SKU                     |
| [Split line item](#split-line-item)                                     | `lineItemVasReturnInventoryLineItem`         | `splitLineItem`                              | VAS split a parcel into multiple inventories     |
| [Warehouse remarks updated](#warehouse-remarks-updated)                 | `warehouseUpdateWarehouseRemarks`            | `warehouseUpdateWarehouseRemarks`            | Warehouse updated remarks on a return request    |
| [Buyer return label generated](#buyer-return-label-generated)           | `buyerReturnRrLabel`                         | `buyerReturnLabelGenerated`                  | Branded return portal label generated for buyer  |
| [Shopify buyer return created](#shopify-buyer-return-created)           | `shopifyBuyerCreateReturn`                   | `shopifyBuyerCreateReturn`                   | Buyer created a return via Shopify integration   |
| [Consolidate shipping cost updated](#consolidate-shipping-cost-updated) | `consolidateShippingOrderShippingFeeUpdated` | `consolidateShippingOrderShippingFeeUpdated` | Consolidated shipping order cost updated         |
| [Consolidate shipping all packed](#consolidate-shipping-all-packed)     | `consolidateShippingOrderInventoryAllPacked` | `consolidateShippingOrderInventoryAllPacked` | All inventories packed for a consolidated order  |
| [Consolidate shipment sent](#consolidate-shipment-sent)                 | `consolidateShippingShipmentSent`            | `consolidateShippingShipmentSent`            | Consolidated shipment dispatched to carrier      |
| [Consolidate shipping AWB updated](#consolidate-shipping-awb-updated)   | `consolidateShippingShipmentShipped`         | `consolidateShippingShipmentShipped`         | Consolidated shipment AWB updated                |
| [Consolidate order completed](#consolidate-order-completed)             | `consolidateShippingOrderCompleted`          | `consolidateShippingOrderCompleted`          | All shipments in a consolidated order shipped    |
| [Consolidate order cancelled](#consolidate-order-cancelled)             | `consolidateShippingOrderCancelled`          | `consolidateShippingOrderCancelled`          | Consolidated order force-cancelled by warehouse  |

***

## Notification Payloads

### Label Result

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

<Warning>
  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`.
</Warning>

`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`                | Map of region codes to regional label URLs                     |

**Success example:**

```json theme={null}
{
  "label": {
    "labelId": 11345,
    "shipmentId": 10825,
    "apiId": 21,
    "refKey": "S210904-0000202",
    "labelRequestStatusCode": "success",
    "serviceType": "usps",
    "trackingNumber": "9201994884299101443342",
    "labelUrl": "https://example.com/label.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:**

```json theme={null}
{
  "label": {
    "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](#inventory-created) events.

<Note>
  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](/reference/seller-reference-number) for the full reconciliation workflow and version differences.
</Note>

`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               |

```json theme={null}
{
  "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.

<Note>
  **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](#warehouse-shipment-arrived-v2) (carries SRN at all three layers in V202207) or [Inventory Handling Complete](#inventory-handling-complete) (carries the Line-Item SRN on `returnInventory.sellerReferenceNumber`). See [Seller Reference Number](/reference/seller-reference-number) for the full reconciliation strategy.
</Note>

`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)    |

```json theme={null}
{
  "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",
    "modifyOn": "2024-07-15T03:29:53.903982",
    "createOn": "2024-07-15T03:29:53.88968",
    "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                  |

```json theme={null}
{
  "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            |
| `modifyOn` / `createOn`                    | Audit timestamps                  |
| `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        |
| `modifyOn`                                 | Last modified timestamp            |

***

### Recall Status Update

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 |

```json theme={null}
{
  "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) |

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

<Warning>
  `trackingNumber` is **not** a top-level field. It lives on the resend shipment: `resendShipmentList[0].trackingNumber`.
</Warning>

Check `resend.resendStatusCode`:

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

```json theme={null}
{
  "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`.

<Note>
  `sellerReferenceNumber` only carries a value when the resend was created by an **Enterprise** account through [Create resend by SKU](/api-reference/resend/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](/api-reference/resend/search-resend-by-seller-reference-number).
</Note>

***

### 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             |

```json theme={null}
{
  "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`) |

```json theme={null}
{
  "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](#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 |

```json theme={null}
{
  "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](#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](#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](#sku-updated))
* `shipment` — the shipment record with full address details, dimensions, weight, cost, and `customFieldMap`
* `returnInventory` — the affected inventory (same structure as [Inventory Handling Complete](#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.

<Info>
  Only applicable to customers integrated with the Return Helper Branded Return service.
</Info>

`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`                                                    | Shipping method                   |
| `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`                 | Shipping method               |
| `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                |
| `awb`                               | Air Waybill number             |
| `serviceProvider`                   | Carrier service provider       |
| `shipDate`                          | Ship date                      |
| `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`     | Inventory identifier       |
| `returnInventoryId`                  | Linked return inventory ID |
| `rma`                                | RMA value                  |
| `consolidateShippingInventoryStatus` | Inventory status           |

***

### 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](#consolidate-shipping-all-packed)) |
| `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](#consolidate-shipment-sent), with the updated `awb` field.

***

### Consolidate Order Completed

Sent when all shipments in a consolidated order have been shipped.

`category: consolidateShippingOrderCompleted` / `action: consolidateShippingOrderCompleted`

The `order` object follows the same structure as [Consolidate Shipping All Packed](#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` | Current status (cancelled) |
| `outboundWarehouseId`            | Outbound warehouse         |
| `shippingMethod`                 | Shipping method            |
| `shippingFee`                    | Shipping fee               |
| `deliveryInstructions`           | Delivery instructions      |
| `customFieldMap`                 | Custom fields              |

***