跳轉到主要內容
此頁面由 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 參考。