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

# Seller Reference Number

> How `sellerReferenceNumber` reconciles Return Helper records with your own order, PO, or SKU system.

`sellerReferenceNumber` is a merchant-supplied identifier you attach to Return Helper records so you can correlate them with your own systems. Return Helper stores the value as-is and returns it on the relevant webhook events.

## Three layers

The field exists at three independent layers, **each of which can hold a different value**. Treat them as separate reconciliation keys.

| Layer          | Field                                         | Typical merchant use                                   |
| -------------- | --------------------------------------------- | ------------------------------------------------------ |
| Return Request | `returnRequest.sellerReferenceNumber`         | Your RMA / return number, or the customer order number |
| Shipment       | `shipment.sellerReferenceNumber`              | Your parcel reference, label batch ID, or order number |
| Line Item      | `returnRequestLineItem.sellerReferenceNumber` | Your SKU or line-item ID                               |

When you create a return through the User API, you supply each layer independently. They appear separately in the relevant webhook payloads.

## Format

A string of **1–50 characters**. Most printable characters are accepted, including `#`, `-`, `_`, and parentheses. Whitespace, control characters, and invisible Unicode (zero-width spaces, BOM) are rejected. The value is stored verbatim — no trimming or case normalisation.

## What Return Helper stores when you omit the field

If you omit `sellerReferenceNumber` at a given layer — or send `null` or `""` — Return Helper substitutes its own internal sequence number for that layer. The field is therefore never empty in the payloads you receive, but the value may be an opaque Return Helper sequence rather than something meaningful to you.

**If you rely on this field for reconciliation, set it explicitly at every layer.**

## How merchants use it

Set `sellerReferenceNumber` at each layer when you create the return, then **reconcile against your own records using the values echoed back in webhook events** — Return Helper sends the field on the same payloads that already drive your return lifecycle, so the corresponding record in your system can be matched directly from the event. Shipment, inventory, and handling webhooks include `sellerReferenceNumber` at the relevant layer.

<Note>
  `sellerReferenceNumber` is a reconciliation key, **not** a uniqueness constraint. Two records in your account can carry the same value. Use it for matching, not for deduplication.
</Note>

## Channel-specific behaviour

When returns are created through a channel integration rather than the User API directly, Return Helper auto-populates `sellerReferenceNumber` with channel-specific identifiers. The values below are what you will see in webhook payloads for these flows.

### Shopify

| Layer          | Value                                                               |
| -------------- | ------------------------------------------------------------------- |
| Return Request | An internal Return Helper sequence — **not** the Shopify return ID. |
| Shipment       | The Shopify **order name** (for example `#1234`).                   |
| Line Item      | The Shopify **product ID**.                                         |

To correlate a Shopify return with your Shopify order, use the **Shipment-layer** value (order name). The Return Request-layer value carries no Shopify-specific information and should be treated as opaque.

### Loop

Loop creates a Return Shipment; the Return Request layer does not exist in this flow.

| Layer                       | Value                                                                          |
| --------------------------- | ------------------------------------------------------------------------------ |
| Return Shipment (top-level) | Loop `returnId`                                                                |
| Shipment                    | Loop `loopReturnLabelRequestId`                                                |
| Line Item                   | The product **SKU** if Loop supplies one; otherwise `loopReturnLabelRequestId` |

To correlate with Loop's records, the top-level value identifies the Loop return; the Shipment-layer value identifies the specific Loop label request.

## Example: setting it on `createReturnShipment`

The [Create Return Shipment](/api-reference/returnshipment/create-return-shipment) endpoint accepts `sellerReferenceNumber` at all three layers. In the request below, each layer is set to a distinct, traceable value so you can see where it surfaces afterwards.

```json highlight={6,10,32} theme={null}
{
  "serviceTypeCode": "fedex_ground",
  "orderTitle": "Customer return — PO 42",
  "totalValue": 30.00,
  "totalValueCurrency": "usd",
  "sellerReferenceNumber": "PO-2026-00042",
  "shipment": {
    "shipToWarehouseId": 2,
    "boxType": "cus",
    "sellerReferenceNumber": "PARCEL-A1",
    "shipFrom": {
      "country": "usa",
      "contactName": "Jane Buyer",
      "phone": "15622708183",
      "email": "user@example.com",
      "street1": "123 Example St",
      "state": "tx",
      "city": "Houston",
      "postalCode": "77235"
    },
    "parcel": {
      "weight": 200,
      "weightUnit": "g",
      "length": 20, "width": 15, "height": 10, "dimensionUnit": "cm",
      "items": [
        {
          "description": "Red T-shirt, size M",
          "weight": 200,
          "weightUom": "g",
          "value": 30.00,
          "valueCurrencyCode": "usd",
          "sellerReferenceNumber": "SKU-RED-MEDIUM"
        }
      ]
    }
  }
}
```

This produces:

| Layer          | Value stored                                        | Surfaces in                                                                                                                                                                                                                                                                               |
| -------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Return Request | `PO-2026-00042` (top-level `sellerReferenceNumber`) | `returnRequest.sellerReferenceNumber` in any event carrying the Return Request object — most commonly [Warehouse Shipment Arrived](/webhooks#warehouse-shipment-arrived-v2) (V202207)                                                                                                     |
| Shipment       | `PARCEL-A1` (`shipment.sellerReferenceNumber`)      | `shipment.sellerReferenceNumber` in [Warehouse Shipment Arrived](/webhooks#warehouse-shipment-arrived-v2)                                                                                                                                                                                 |
| Line Item      | `SKU-RED-MEDIUM` (per-item `sellerReferenceNumber`) | `returnInventoryList[].sellerReferenceNumber` and `lineItems[].sellerReferenceNumber` in [Warehouse Shipment Arrived](/webhooks#warehouse-shipment-arrived-v2) (V202207); `returnInventory.sellerReferenceNumber` in [Inventory Handling Complete](/webhooks#inventory-handling-complete) |

### What the notifications look like

When the warehouse marks the parcel received, the `markShipmentArrive` event (V202207) echoes the values you set at all three layers in a single payload (trimmed below for clarity):

```json highlight={4,10,20,27} theme={null}
{
  "returnRequest": {
    "returnRequestId": 74484,
    "sellerReferenceNumber": "PO-2026-00042",
    "returnTitle": "Customer return - PO 42",
    "rma": "USE-2-260514-D00004-15"
  },
  "shipment": {
    "shipmentId": 43325,
    "sellerReferenceNumber": "PARCEL-A1",
    "trackingNumber": "RHDEMO202606011780282223",
    "shipmentStatusCode": 6,
    "shipmentServiceType": "fedex_ground",
    "receiveDate": "2026-06-01T03:02:00Z"
  },
  "returnInventoryList": [
    {
      "returnInventoryId": 22501,
      "returnRequestLineItemId": 50560,
      "sellerReferenceNumber": "SKU-RED-MEDIUM",
      "rma": "USE-2-260514-D00004-15"
    }
  ],
  "lineItems": [
    {
      "returnRequestLineItemId": 50560,
      "sellerReferenceNumber": "SKU-RED-MEDIUM"
    }
  ],
  "category": "rsl",
  "action": "markShipmentArrive",
  "version": "202207"
}
```

The Line-Item value also surfaces on the inventory record in `completeInventoryHandling` once handling is finished:

```json highlight={6,7} theme={null}
{
  "returnInventory": {
    "returnInventoryId": 22501,
    "returnRequestId": 74484,
    "returnRequestLineItemId": 50560,
    "sellerReferenceNumber": "SKU-RED-MEDIUM",
    "returnRequestLineItemNumber": "SKU-RED-MEDIUM",
    "description": "Red T-shirt size M",
    "handlingCode": 2,
    "handlingStatusCode": 2,
    "completeOn": "2026-06-01T04:06:00Z",
    "rma": "USE-2-260514-D00004-15"
  },
  "category": "rinv",
  "action": "completeInventoryHandling",
  "version": "202207"
}
```

<Note>
  **V202207 field aliasing.** In V202207 webhook payloads, the legacy `*Number` fields (`returnRequestNumber`, `shipmentNumber`, `returnRequestLineItemNumber`) are aliases for `sellerReferenceNumber` and carry the **same value** — not Return Helper's internal sequence. To reference a Return Helper record reliably, use the `*Id` fields (`returnRequestId`, `shipmentId`, `returnInventoryId`).
</Note>

The synchronous `CreateReturnShipment` response does **not** echo `sellerReferenceNumber` at any layer — it returns `returnRequestNumber` (Return Helper's internal sequence) and `referenceNumber` (your `orderNumber`) only. Use the webhook payloads above for SRN-based reconciliation.

## Reconciliation workflow

For returns created via `createReturnShipment`:

1. **Call `createReturnShipment`** with `sellerReferenceNumber` set at every layer that matters to your reconciliation. The synchronous response returns Return Helper's internal IDs (`returnRequestId`, `shipmentId`, `labelId`) but does **not** echo `sellerReferenceNumber`.
2. **Wait for the `markShipmentArrive` webhook** (see version differences below). This is the first event that carries your SRN values back, joined to Return Helper's identifiers.
3. **Persist the mapping** between your order (by SRN) and `returnInventoryId`. SRN is the join key; `returnInventoryId` is what you will use for every operation afterwards. Many merchants also store `returnRequestId` and `shipmentId` for higher-level grouping, but the operational primary key once the parcel has been received is `returnInventoryId`.
4. **From this point on, communicate with Return Helper using `returnInventoryId`** — for handling instructions, VAS, recall, dispose, and any subsequent inventory-level webhook such as [Inventory Handling Complete](/webhooks#inventory-handling-complete). Your stored mapping routes those events back to the right customer order.

For returns created via channel integrations (Shopify, Loop), step 1 is replaced by the channel pushing the return into Return Helper; the auto-populated SRN values are described in [Channel-specific behaviour](#channel-specific-behaviour). Steps 2–4 are identical.

### `markShipmentArrive` versions

Two payload shapes for `markShipmentArrive` exist. **V202207 is the default for new accounts** — your account receives this version unless you explicitly contact Return Helper support to switch to V202407.

| Version                  | Payload shape                                                                                           | Inventory delivery                                                                                         |
| ------------------------ | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **V202207** (default)    | Bundled — `shipment`, `returnRequest`, `returnInventoryList[]`, `lineItems[]`, `label` all in one event | Inline in `returnInventoryList[]`                                                                          |
| **V202407** (on request) | Lean — `shipment` object only                                                                           | Streamed — followed by one [`newInventoryCreated`](/webhooks#inventory-created) event per inventory record |

Both produce the same lifecycle and the same end-state. The difference is delivery style: V202207 packs everything into one fat payload (one event to process), V202407 emits a tighter `markShipmentArrive` followed by separate inventory events (smaller payloads, better when a single shipment splits into many inventories). If you expect shipments that frequently produce many inventories (multi-package or VAS-split parcels), ask support to enable V202407.

A V202407 `markShipmentArrive` payload for the same workflow looks like:

```json highlight={7} theme={null}
{
  "shipment": {
    "shipmentId": "43328",
    "returnRequestId": "74487",
    "trackingNumber": "RHDEMO202606011780289491",
    "referenceNumber": "PO-2026-00042",
    "sellerReferenceNumber": "PARCEL-A1",
    "shipToWarehouseId": 2,
    "receiveDate": "2026-06-01T04:54:25Z"
  },
  "category": "rsl",
  "action": "markShipmentArrive",
  "version": "202407"
}
```

Only the Shipment-layer SRN appears. `sellerReferenceNumber` and `referenceNumber` are independent fields — V202407 does not use the `*Number` aliasing pattern seen in V202207.

**Impact on the workflow above:**

* **V202207** — step 2 is a single join: one `markShipmentArrive` event gives you every SRN layer and every Return Helper ID needed for step 3.
* **V202407** — step 2 becomes a two-stage join. `markShipmentArrive` gives you `shipment.sellerReferenceNumber` ↔ `shipmentId`. Each subsequent `newInventoryCreated` carries `shipmentId` (which you look up in your mapping from step 1) and the new `returnInventoryId` (which you then persist for step 3 onwards). Because `newInventoryCreated` does not carry `sellerReferenceNumber`, the `shipmentId` chain is the only join route — you must store the SRN ↔ `shipmentId` mapping before the inventory events arrive.

## Recommendations

* Set `sellerReferenceNumber` explicitly at every layer that matters to your reconciliation. Do not rely on the fallback.
* Treat the three layers as independent. For Shopify they always differ; for direct User API use they can also differ.
* Use webhook payloads for tracking lifecycle events rather than polling list endpoints. See the [Webhooks reference](/webhooks) for which events include which layer's `sellerReferenceNumber`.