sellerReferenceNumber 是您附加到 Return Helper 记录上的卖家自定义标识符，用于把这些记录与您自己的系统关联起来。Return Helper 原样存储该值，并在相关 Webhook 事件中回传给您。
三个层级
该字段存在于三个互相独立的层级上，每个层级可以承载不同的值。请将它们视为各自独立的对账键。
当您通过 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
要把 Shopify 退货与您的 Shopify 订单对上，请使用 Shipment 层级的值（订单名称）。Return Request 层级的值并不携带 Shopify 特定信息，应视为不透明。
Loop
Loop 创建的是一份 Return Shipment；该流程中没有 Return Request 层级。
要与 Loop 的记录对账：顶层值标识 Loop 的退货；Shipment 层级的值标识具体的 Loop 标签请求。
示例：在 createReturnShipment 上设置
Create Return Shipment 端点在三个层级都接受 sellerReferenceNumber。在下面的请求中，每个层级都设了一个独特、易追踪的值，方便您观察它后续出现在何处。
通知长什么样
当仓库标记 Shipment 为已收货时，markShipmentArrive 事件（V202207）会在同一份负载中回传您在三个层级上设的值（下面已为清晰起见做了精简）：
completeInventoryHandling 中作为库存记录上的字段出现：
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 创建的退货：
- 调用
createReturnShipment，在您需要对账的每个层级上设定sellerReferenceNumber。同步响应会返回 Return Helper 的内部 ID（returnRequestId、shipmentId、labelId），但不会回传sellerReferenceNumber。 - 等待
markShipmentArriveWebhook（版本差异见下文）。这是第一个把您的 SRN 值与 Return Helper 标识符绑在一起回传给您的事件。 - 持久化映射——把您的订单（按 SRN）与
returnInventoryId关联起来。SRN 是连接键；returnInventoryId是您此后用于所有操作的主键。许多商家也会同时存returnRequestId与shipmentId用于更高层的分组，但包裹收货后操作上的主键是returnInventoryId。 - 从此往后，使用
returnInventoryId与 Return Helper 通信——用于处理指令、VAS、Recall、Dispose，以及任何后续的库存层级 Webhook，例如 Inventory Handling Complete。您持久化的映射会把那些事件路由回正确的客户订单。
markShipmentArrive 版本
markShipmentArrive 存在两种负载形态。V202207 是新账户的默认版本——您的账户接收这一版本，除非您明确联系 Return Helper 客服切换到 V202407。
两者产生的是相同的生命周期与相同的终态。区别在于投递方式：V202207 把所有信息塞进一个大负载里（一次处理完事），V202407 发出更精简的
markShipmentArrive 后再单独投递库存事件（每条负载更小，当一个 shipment 拆出很多库存时更合适）。如果您预期 shipment 经常会产生很多库存（多包裹或 VAS 拆件），请联系客服启用 V202407。
针对同一工作流的 V202407 markShipmentArrive 负载长这样：
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 参考。