メインコンテンツへスキップ
このページはAIによって自動翻訳されています。不明点や相違がある場合は、英語版を正式版として参照してください。
sellerReferenceNumber は、Return Helper のレコードに付与する出品者側の識別子で、ご自身のシステムとの紐付けに使用します。Return Helper は値をそのまま保存し、関連する Webhook イベントでそのまま返却します。

​
3 つのレイヤー

このフィールドは 互いに独立した 3 つのレイヤーに存在し、各レイヤーがそれぞれ異なる値を持ち得ます。それぞれを別個の突合キーとして扱ってください。
レイヤーフィールド典型的な使い方
Return RequestreturnRequest.sellerReferenceNumberお客様の RMA / 返品番号、または顧客の注文番号
Shipmentshipment.sellerReferenceNumberお客様の荷物参照番号、ラベルのバッチ ID、または注文番号
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 は突合キーであり、一意性制約ではありません。アカウント内の 2 つのレコードが同じ値を持つことも可能です。マッチング用に使用し、重複排除には使用しないでください。

​
チャネル固有の挙動

返品が User API ではなくチャネル連携で作成された場合、Return Helper は sellerReferenceNumber にチャネル固有の識別子を自動的に充当します。以下の値が、それらのフローの Webhook ペイロードに現れる値です。

​
Shopify

レイヤー値
Return RequestReturn Helper の内部シーケンス番号 — Shopify の return ID では ありません。
ShipmentShopify の 注文名（order name）（例：#1234）。
Line ItemShopify の 商品 ID（product 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 エンドポイントは 3 つのレイヤーすべてで 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（アイテムごとの sellerReferenceNumber）Warehouse Shipment Arrived（V202207）の returnInventoryList[].sellerReferenceNumber と lineItems[].sellerReferenceNumber；Inventory Handling Complete の returnInventory.sellerReferenceNumber

​
通知の見え方

倉庫が Shipment を受領済みとしてマークすると、markShipmentArrive イベント（V202207）は同一ペイロード内で 3 つのレイヤーすべてに設定した値を返却します（明確化のため抜粋）： 
{
  "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）のみです。SRN ベースの突合には上述の Webhook ペイロードを利用してください。

​
突合ワークフロー

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、および Inventory Handling Complete などの後続の在庫レイヤー Webhook で使用します。永続化したマッピングが、これらのイベントを正しい顧客注文へとルーティングします。
チャネル連携（Shopify、Loop）で作成された返品の場合、ステップ 1 はチャネルが返品を Return Helper にプッシュする処理で置き換わります。自動充当された SRN 値は チャネル固有の挙動 を参照してください。ステップ 2〜4 は同じです。

​
markShipmentArrive のバージョン

markShipmentArrive には 2 つのペイロード形態が存在します。V202207 は新規アカウントのデフォルト で、明示的に Return Helper のサポートへ V202407 への切替を依頼しない限り、お客様のアカウントはこのバージョンを受信します。
バージョンペイロード形態在庫の配信方式
V202207（デフォルト）バンドル — shipment、returnRequest、returnInventoryList[]、lineItems[]、label が同一イベントに同梱returnInventoryList[] 内にインライン
V202407（要望に応じて）リーン — shipment オブジェクトのみストリーミング — 在庫レコードごとに newInventoryCreated イベントが続く
両方とも同じライフサイクル・同じ最終状態を生み出します。違いは配信スタイルです：V202207 はすべての情報を 1 つの大きなペイロードにまとめて処理を 1 回で済ませ、V202407 はより軽量な markShipmentArrive の後に在庫イベントを個別配信します（ペイロードがコンパクトで、1 つの 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 は単一の結合で完結します：1 つの markShipmentArrive イベントがステップ 3 に必要なすべての SRN レイヤーとすべての Return Helper ID を提供します。
  • V202407 — ステップ 2 は二段階の結合になります。markShipmentArrive は shipment.sellerReferenceNumber ↔ shipmentId を提供します。その後の各 newInventoryCreated は shipmentId（ステップ 1 で保存したマッピングで参照）と新規 returnInventoryId（ステップ 3 以降のために永続化）を運びます。newInventoryCreated 自身は sellerReferenceNumber を運ばないため、shipmentId チェーンが唯一の結合経路です — 在庫イベントが到着する 前 に SRN ↔ shipmentId のマッピングを保存しておく必要があります。

​
推奨

  • 突合に重要なすべてのレイヤーで、sellerReferenceNumber を 明示的に 設定してください。フォールバックに依存しないでください。
  • 3 つのレイヤーを独立したものとして扱ってください。Shopify では常に異なり、User API を直接使用する場合でも異なる可能性があります。
  • ライフサイクルイベントの追跡には、リスト系エンドポイントをポーリングするのではなく、Webhook ペイロードを使用してください。どのイベントがどのレイヤーの sellerReferenceNumber を含むかは Webhooks リファレンス を参照してください。