Skip to main content
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.
LayerFieldTypical merchant use
Return RequestreturnRequest.sellerReferenceNumberYour RMA / return number, or the customer order number
Shipmentshipment.sellerReferenceNumberYour parcel reference, label batch ID, or order number
Line ItemreturnRequestLineItem.sellerReferenceNumberYour 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.
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.

​
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

LayerValue
Return RequestAn internal Return Helper sequence — not the Shopify return ID.
ShipmentThe Shopify order name (for example #1234).
Line ItemThe 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.
LayerValue
Return Shipment (top-level)Loop returnId
ShipmentLoop loopReturnLabelRequestId
Line ItemThe 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 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. 
{
  "serviceTypeCode": "fedex_ground",
  "orderTitle": "Customer return — PO 42",
  "orderNumber": "PO-2026-00042",
  "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:
LayerValue storedSurfaces in
Return RequestPO-2026-00042 (top-level sellerReferenceNumber)returnRequest.sellerReferenceNumber in any event carrying the Return Request object — most commonly Warehouse Shipment Arrived (V202207)
ShipmentPARCEL-A1 (shipment.sellerReferenceNumber)shipment.sellerReferenceNumber in Warehouse Shipment Arrived
Line ItemSKU-RED-MEDIUM (per-item sellerReferenceNumber)returnInventoryList[].sellerReferenceNumber and lineItems[].sellerReferenceNumber in Warehouse Shipment Arrived (V202207); returnInventory.sellerReferenceNumber in 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): 
{
  "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: 
{
  "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"
}
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).
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. 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. 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.
VersionPayload shapeInventory delivery
V202207 (default)Bundled — shipment, returnRequest, returnInventoryList[], lineItems[], label all in one eventInline in returnInventoryList[]
V202407 (on request)Lean — shipment object onlyStreamed — followed by one newInventoryCreated 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: 
{
  "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 for which events include which layer’s sellerReferenceNumber.