跳转到主要内容
此页面由 AI 自动翻译。如有任何疑问或不一致之处，请以英文版本为准。
sellerReferenceNumber 是您附加到 Return Helper 记录上的卖家自定义标识符，用于把这些记录与您自己的系统关联起来。Return Helper 原样存储该值，并在相关 Webhook 事件中回传给您。

​
三个层级

该字段存在于三个互相独立的层级上，每个层级可以承载不同的值。请将它们视为各自独立的对账键。
层级字段典型用途
Return RequestreturnRequest.sellerReferenceNumber您的 RMA / 退货单号，或客户订单号
Shipmentshipment.sellerReferenceNumber您的包裹参考号、标签批次号或订单号
Line ItemreturnRequestLineItem.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。
sellerReferenceNumber 是对账键，不是唯一性约束。您账户中的两条记录可以承载相同的值。请用它做匹配，而不是去重。

​
渠道集成的特定行为

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

​
Shopify

层级值
Return RequestReturn Helper 内部序列号——不是 Shopify 的 return ID。
ShipmentShopify 的订单名称（例如 #1234）。
Line ItemShopify 的商品 ID。
要把 Shopify 退货与您的 Shopify 订单对上，请使用 Shipment 层级的值（订单名称）。Return Request 层级的值并不携带 Shopify 特定信息，应视为不透明。

​
Loop

Loop 创建的是一份 Return Shipment；该流程中没有 Return Request 层级。
层级值
Return Shipment（顶层）Loop returnId
ShipmentLoop loopReturnLabelRequestId
Line ItemLoop 提供时为商品 SKU；否则为 loopReturnLabelRequestId
要与 Loop 的记录对账：顶层值标识 Loop 的退货；Shipment 层级的值标识具体的 Loop 标签请求。

​
示例：在 createReturnShipment 上设置

Create Return Shipment 端点在三个层级都接受 sellerReferenceNumber。在下面的请求中，每个层级都设了一个独特、易追踪的值，方便您观察它后续出现在何处。 
{
  "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"
        }
      ]
    }
  }
}
会产生：
层级存储的值在哪里出现
Return RequestPO-2026-00042（顶层 sellerReferenceNumber）任何携带 Return Request 对象的事件中的 returnRequest.sellerReferenceNumber——最常见是 Warehouse Shipment Arrived（V202207）
ShipmentPARCEL-A1（shipment.sellerReferenceNumber）Warehouse Shipment Arrived 中的 shipment.sellerReferenceNumber
Line ItemSKU-RED-MEDIUM（每条 item 的 sellerReferenceNumber）Warehouse Shipment Arrived（V202207）中的 returnInventoryList[].sellerReferenceNumber 与 lineItems[].sellerReferenceNumber；Inventory Handling Complete 中的 returnInventory.sellerReferenceNumber

​
通知长什么样

当仓库标记 Shipment 为已收货时，markShipmentArrive 事件（V202207）会在同一份负载中回传您在三个层级上设的值（下面已为清晰起见做了精简）： 
{
  "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 中作为库存记录上的字段出现： 
{
  "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 字段别名。 在 V202207 Webhook 负载中，遗留的 *Number 字段（returnRequestNumber、shipmentNumber、returnRequestLineItemNumber）是 sellerReferenceNumber 的别名，承载相同的值——并不是 Return Helper 的内部序列。如需可靠地引用 Return Helper 记录，请使用 *Id 字段（returnRequestId、shipmentId、returnInventoryId）。
同步的 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。您持久化的映射会把那些事件路由回正确的客户订单。
对于通过渠道集成（Shopify、Loop）创建的退货，第 1 步由渠道把退货推送到 Return Helper 替代；自动填充的 SRN 值见 渠道集成的特定行为。第 2–4 步完全一致。

​
markShipmentArrive 版本

markShipmentArrive 存在两种负载形态。V202207 是新账户的默认版本——您的账户接收这一版本，除非您明确联系 Return Helper 客服切换到 V202407。
版本负载形态库存投递方式
V202207（默认）打包——shipment、returnRequest、returnInventoryList[]、lineItems[]、label 一次性放在同一个事件里内嵌于 returnInventoryList[]
V202407（按需开启）精简——仅含 shipment 对象流式——其后跟随每条库存记录一个 newInventoryCreated 事件
两者产生的是相同的生命周期与相同的终态。区别在于投递方式：V202207 把所有信息塞进一个大负载里（一次处理完事），V202407 发出更精简的 markShipmentArrive 后再单独投递库存事件（每条负载更小，当一个 shipment 拆出很多库存时更合适）。如果您预期 shipment 经常会产生很多库存（多包裹或 VAS 拆件），请联系客服启用 V202407。 针对同一工作流的 V202407 markShipmentArrive 负载长这样： 
{
  "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 参考。