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 參考。