sellerReferenceNumber は、Return Helper のレコードに付与する出品者側の識別子で、ご自身のシステムとの紐付けに使用します。Return Helper は値をそのまま保存し、関連する Webhook イベントでそのまま返却します。
3 つのレイヤー
このフィールドは 互いに独立した 3 つのレイヤーに存在し、各レイヤーがそれぞれ異なる値を持ち得ます。それぞれを別個の突合キーとして扱ってください。
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
Shopify の返品を Shopify の注文と突合するには、Shipment レイヤー の値（注文名）を使用してください。Return Request レイヤーの値には Shopify 固有の情報は含まれず、不透明な値として扱ってください。
Loop
Loop は Return Shipment を作成しますが、このフローには Return Request レイヤーは存在しません。
Loop のレコードと突合するには、トップレベルの値で Loop の返品を、Shipment レイヤーの値で個別の Loop ラベル要求を識別します。
例：createReturnShipment での設定
Create Return Shipment エンドポイントは 3 つのレイヤーすべてで sellerReferenceNumber を受け付けます。下のリクエストでは、各レイヤーに区別しやすい固有の値を設定して、後段でどこに現れるかを追跡できるようにしています。
通知の見え方
倉庫が Shipment を受領済みとしてマークすると、markShipmentArrive イベント（V202207）は同一ペイロード内で 3 つのレイヤーすべてに設定した値を返却します（明確化のため抜粋）：
completeInventoryHandling でも在庫レコードのフィールドとして現れます：
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 で作成した返品の場合：
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、および Inventory Handling Complete などの後続の在庫レイヤー Webhook で使用します。永続化したマッピングが、これらのイベントを正しい顧客注文へとルーティングします。
markShipmentArrive のバージョン
markShipmentArrive には 2 つのペイロード形態が存在します。V202207 は新規アカウントのデフォルト で、明示的に Return Helper のサポートへ V202407 への切替を依頼しない限り、お客様のアカウントはこのバージョンを受信します。
両方とも同じライフサイクル・同じ最終状態を生み出します。違いは配信スタイルです：V202207 はすべての情報を 1 つの大きなペイロードにまとめて処理を 1 回で済ませ、V202407 はより軽量な
markShipmentArrive の後に在庫イベントを個別配信します（ペイロードがコンパクトで、1 つの shipment が多数の在庫に分割される場合に適しています）。shipment が頻繁に多数の在庫を生成する場合（複数パッケージ、VAS 分割パーセル）は、サポートに V202407 の有効化を依頼してください。
同じワークフローの V202407 markShipmentArrive ペイロードは次のようになります：
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 リファレンス を参照してください。