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

> 如何使用 `sellerReferenceNumber` 把 Return Helper 记录与您自己的订单、PO 或 SKU 系统对账。

<Warning>
  此页面由 AI 自动翻译。如有任何疑问或不一致之处，请以[英文版本](/reference/seller-reference-number)为准。
</Warning>

`sellerReferenceNumber` 是您附加到 Return Helper 记录上的卖家自定义标识符，用于把这些记录与您自己的系统关联起来。Return Helper 原样存储该值，并在相关 Webhook 事件中回传给您。

## 三个层级

该字段存在于三个**互相独立**的层级上，**每个层级可以承载不同的值**。请将它们视为各自独立的对账键。

| 层级             | 字段                                            | 典型用途                 |
| -------------- | --------------------------------------------- | -------------------- |
| Return Request | `returnRequest.sellerReferenceNumber`         | 您的 RMA / 退货单号，或客户订单号 |
| Shipment       | `shipment.sellerReferenceNumber`              | 您的包裹参考号、标签批次号或订单号    |
| Line Item      | `returnRequestLineItem.sellerReferenceNumber` | 您的 SKU 或行项目 ID       |

当您通过 User API 创建一笔退货时，可在各层级独立赋值。它们会在相应的 Webhook 负载中分别出现。

## 格式

字符串长度 **1–50 字符**。大多数可打印字符均被接受，包括 `#`、`-`、`_` 与括号。空白字符、控制字符以及不可见 Unicode（零宽空格、BOM）会被拒绝。值原样保存——不做修剪或大小写归一化。

## 省略字段时 Return Helper 会存什么

如果您在某个层级未提供 `sellerReferenceNumber`——或传 `null` 或 `""`——Return Helper 会以其内部序列号替代该层级的值。因此该字段在您收到的负载中**永远不为空**，但值可能是一个对您来说没有意义的 Return Helper 序列号。

**如果您依赖该字段进行对账，请在每个层级上显式赋值。**

## 商家如何使用

在创建退货时为每个层级显式设定 `sellerReferenceNumber`，然后**用 Webhook 事件中回传的值与您自己的记录进行对账**——Return Helper 会在驱动您退货生命周期的同一组负载中携带该字段，因此事件中携带的信息足以直接匹配到您系统中的对应记录。Shipment、库存与处理类 Webhook 事件均会在相应层级包含 `sellerReferenceNumber`。

<Note>
  `sellerReferenceNumber` 是对账键，**不是**唯一性约束。您账户中的两条记录可以承载相同的值。请用它做匹配，而不是去重。
</Note>

## 渠道集成的特定行为

当退货是通过渠道集成而非直接通过 User API 创建时，Return Helper 会用渠道特定的标识符自动填充 `sellerReferenceNumber`。下列值就是您在这些流程的 Webhook 负载中会看到的。

### Shopify

| 层级             | 值                                                |
| -------------- | ------------------------------------------------ |
| Return Request | Return Helper 内部序列号——**不是** Shopify 的 return ID。 |
| Shipment       | Shopify 的**订单名称**（例如 `#1234`）。                   |
| Line Item      | Shopify 的**商品 ID**。                              |

要把 Shopify 退货与您的 Shopify 订单对上，请使用 **Shipment 层级**的值（订单名称）。Return Request 层级的值并不携带 Shopify 特定信息，应视为不透明。

### Loop

Loop 创建的是一份 Return Shipment；该流程中没有 Return Request 层级。

| 层级                  | 值                                                  |
| ------------------- | -------------------------------------------------- |
| Return Shipment（顶层） | Loop `returnId`                                    |
| Shipment            | Loop `loopReturnLabelRequestId`                    |
| Line Item           | Loop 提供时为商品 **SKU**；否则为 `loopReturnLabelRequestId` |

要与 Loop 的记录对账：顶层值标识 Loop 的退货；Shipment 层级的值标识具体的 Loop 标签请求。

## 示例：在 `createReturnShipment` 上设置

[Create Return Shipment](/zh-Hans/api-reference/returnshipment/create-return-shipment) 端点在三个层级都接受 `sellerReferenceNumber`。在下面的请求中，每个层级都设了一个独特、易追踪的值，方便您观察它后续出现在何处。

```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"
        }
      ]
    }
  }
}
```

会产生：

| 层级             | 存储的值                                                | 在哪里出现                                                                                                                                                                                                                                                                                                |
| -------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Return Request | `PO-2026-00042`（顶层 `sellerReferenceNumber`）         | 任何携带 Return Request 对象的事件中的 `returnRequest.sellerReferenceNumber`——最常见是 [Warehouse Shipment Arrived](/zh-Hans/webhooks#warehouse-shipment-arrived-v2)（V202207）                                                                                                                                       |
| Shipment       | `PARCEL-A1`（`shipment.sellerReferenceNumber`）       | [Warehouse Shipment Arrived](/zh-Hans/webhooks#warehouse-shipment-arrived-v2) 中的 `shipment.sellerReferenceNumber`                                                                                                                                                                                    |
| Line Item      | `SKU-RED-MEDIUM`（每条 item 的 `sellerReferenceNumber`） | [Warehouse Shipment Arrived](/zh-Hans/webhooks#warehouse-shipment-arrived-v2)（V202207）中的 `returnInventoryList[].sellerReferenceNumber` 与 `lineItems[].sellerReferenceNumber`；[Inventory Handling Complete](/zh-Hans/webhooks#inventory-handling-complete) 中的 `returnInventory.sellerReferenceNumber` |

### 通知长什么样

当仓库标记 Shipment 为已收货时，`markShipmentArrive` 事件（V202207）会在同一份负载中回传您在三个层级上设的值（下面已为清晰起见做了精简）：

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

处理完成后，Line Item 层级的值也会在 `completeInventoryHandling` 中作为库存记录上的字段出现：

```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 字段别名。** 在 V202207 Webhook 负载中，遗留的 `*Number` 字段（`returnRequestNumber`、`shipmentNumber`、`returnRequestLineItemNumber`）是 `sellerReferenceNumber` 的别名，承载**相同的值**——并不是 Return Helper 的内部序列。如需可靠地引用 Return Helper 记录，请使用 `*Id` 字段（`returnRequestId`、`shipmentId`、`returnInventoryId`）。
</Note>

同步的 `CreateReturnShipment` 响应**不会**在任何层级回传 `sellerReferenceNumber`——它只返回 `returnRequestNumber`（Return Helper 内部序列）与 `referenceNumber`（您传入的 `orderNumber`）。请用上面的 Webhook 负载做基于 SRN 的对账。

## 对账工作流

对于通过 `createReturnShipment` 创建的退货：

1. **调用 `createReturnShipment`**，在您需要对账的每个层级上设定 `sellerReferenceNumber`。同步响应会返回 Return Helper 的内部 ID（`returnRequestId`、`shipmentId`、`labelId`），但**不会**回传 `sellerReferenceNumber`。
2. **等待 `markShipmentArrive` Webhook**（版本差异见下文）。这是第一个把您的 SRN 值与 Return Helper 标识符绑在一起回传给您的事件。
3. **持久化映射**——把您的订单（按 SRN）与 `returnInventoryId` 关联起来。SRN 是连接键；`returnInventoryId` 是您此后用于所有操作的主键。许多商家也会同时存 `returnRequestId` 与 `shipmentId` 用于更高层的分组，但包裹收货后操作上的主键是 `returnInventoryId`。
4. **从此往后，使用 `returnInventoryId` 与 Return Helper 通信**——用于处理指令、VAS、Recall、Dispose，以及任何后续的库存层级 Webhook，例如 [Inventory Handling Complete](/zh-Hans/webhooks#inventory-handling-complete)。您持久化的映射会把那些事件路由回正确的客户订单。

对于通过渠道集成（Shopify、Loop）创建的退货，第 1 步由渠道把退货推送到 Return Helper 替代；自动填充的 SRN 值见 [渠道集成的特定行为](#channel-specific-behaviour)。第 2–4 步完全一致。

### `markShipmentArrive` 版本

`markShipmentArrive` 存在两种负载形态。**V202207 是新账户的默认版本**——您的账户接收这一版本，除非您明确联系 Return Helper 客服切换到 V202407。

| 版本                | 负载形态                                                                                     | 库存投递方式                                                                           |
| ----------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| **V202207**（默认）   | 打包——`shipment`、`returnRequest`、`returnInventoryList[]`、`lineItems[]`、`label` 一次性放在同一个事件里 | 内嵌于 `returnInventoryList[]`                                                      |
| **V202407**（按需开启） | 精简——仅含 `shipment` 对象                                                                     | 流式——其后跟随每条库存记录一个 [`newInventoryCreated`](/zh-Hans/webhooks#inventory-created) 事件 |

两者产生的是相同的生命周期与相同的终态。区别在于投递方式：V202207 把所有信息塞进一个大负载里（一次处理完事），V202407 发出更精简的 `markShipmentArrive` 后再单独投递库存事件（每条负载更小，当一个 shipment 拆出很多库存时更合适）。如果您预期 shipment 经常会产生很多库存（多包裹或 VAS 拆件），请联系客服启用 V202407。

针对同一工作流的 V202407 `markShipmentArrive` 负载长这样：

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

只有 Shipment 层级的 SRN 出现。`sellerReferenceNumber` 与 `referenceNumber` 是相互独立的字段——V202407 不使用 V202207 那种 `*Number` 别名模式。

**对上面工作流的影响：**

* **V202207**——第 2 步是一次连接：一个 `markShipmentArrive` 事件就给您第 3 步所需的全部 SRN 层级与全部 Return Helper ID。
* **V202407**——第 2 步变成两阶段连接。`markShipmentArrive` 给您 `shipment.sellerReferenceNumber` ↔ `shipmentId`。其后每条 `newInventoryCreated` 携带 `shipmentId`（您在第 1 步存的映射里查它），以及新的 `returnInventoryId`（您把它持久化以供第 3 步起使用）。因为 `newInventoryCreated` 本身不携带 `sellerReferenceNumber`，`shipmentId` 链条是唯一的连接路径——您必须在库存事件到达**之前**就把 SRN ↔ `shipmentId` 映射存好。

## 建议

* 在每个对账重要的层级上**显式**设置 `sellerReferenceNumber`，不要依赖默认值。
* 把三个层级视为各自独立。Shopify 下它们总是不同的；直接通过 User API 使用时也可能不同。
* 用 Webhook 负载来跟踪生命周期事件，而不是轮询列表端点。具体哪个事件携带哪个层级的 `sellerReferenceNumber`，参见 [Webhooks 参考](/zh-Hans/webhooks)。