> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.returnhelper.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Seller Reference Number
> Return Helper のレコードをご自身の注文・PO・SKU システムと `sellerReferenceNumber` で突合する方法。
このページはAIによって自動翻訳されています。不明点や相違がある場合は、[英語版](/reference/seller-reference-number)を正式版として参照してください。
`sellerReferenceNumber` は、Return Helper のレコードに付与する出品者側の識別子で、ご自身のシステムとの紐付けに使用します。Return Helper は値をそのまま保存し、関連する Webhook イベントでそのまま返却します。
## 3 つのレイヤー
このフィールドは **互いに独立した** 3 つのレイヤーに存在し、**各レイヤーがそれぞれ異なる値を持ち得ます**。それぞれを別個の突合キーとして扱ってください。
| レイヤー | フィールド | 典型的な使い方 |
| -------------- | --------------------------------------------- | ----------------------------- |
| Return Request | `returnRequest.sellerReferenceNumber` | お客様の RMA / 返品番号、または顧客の注文番号 |
| Shipment | `shipment.sellerReferenceNumber` | お客様の荷物参照番号、ラベルのバッチ ID、または注文番号 |
| Line Item | `returnRequestLineItem.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 Request | Return Helper の内部シーケンス番号 — Shopify の return ID では **ありません**。 |
| Shipment | Shopify の **注文名（order name）**（例：`#1234`）。 |
| Line Item | Shopify の **商品 ID（product ID）**。 |
Shopify の返品を Shopify の注文と突合するには、**Shipment レイヤー** の値（注文名）を使用してください。Return Request レイヤーの値には Shopify 固有の情報は含まれず、不透明な値として扱ってください。
### Loop
Loop は Return Shipment を作成しますが、このフローには Return Request レイヤーは存在しません。
| レイヤー | 値 |
| ----------------------- | ----------------------------------------------------------- |
| Return Shipment（トップレベル） | Loop の `returnId` |
| Shipment | Loop の `loopReturnLabelRequestId` |
| Line Item | Loop が提供している場合は商品の **SKU**、それ以外は `loopReturnLabelRequestId` |
Loop のレコードと突合するには、トップレベルの値で Loop の返品を、Shipment レイヤーの値で個別の Loop ラベル要求を識別します。
## 例：`createReturnShipment` での設定
[Create Return Shipment](/ja/api-reference/returnshipment/create-return-shipment) エンドポイントは 3 つのレイヤーすべてで `sellerReferenceNumber` を受け付けます。下のリクエストでは、各レイヤーに区別しやすい固有の値を設定して、後段でどこに現れるかを追跡できるようにしています。
```json highlight={6,10,32} theme={null}
{
"serviceTypeCode": "fedex_ground",
"orderTitle": "Customer return — PO 42",
"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 Request | `PO-2026-00042`（トップレベルの `sellerReferenceNumber`） | Return Request オブジェクトを含む任意のイベントの `returnRequest.sellerReferenceNumber` — もっとも一般的には [Warehouse Shipment Arrived](/ja/webhooks#warehouse-shipment-arrived-v2)（V202207） |
| Shipment | `PARCEL-A1`（`shipment.sellerReferenceNumber`） | [Warehouse Shipment Arrived](/ja/webhooks#warehouse-shipment-arrived-v2) の `shipment.sellerReferenceNumber` |
| Line Item | `SKU-RED-MEDIUM`（アイテムごとの `sellerReferenceNumber`） | [Warehouse Shipment Arrived](/ja/webhooks#warehouse-shipment-arrived-v2)（V202207）の `returnInventoryList[].sellerReferenceNumber` と `lineItems[].sellerReferenceNumber`；[Inventory Handling Complete](/ja/webhooks#inventory-handling-complete) の `returnInventory.sellerReferenceNumber` |
### 通知の見え方
倉庫が Shipment を受領済みとしてマークすると、`markShipmentArrive` イベント（V202207）は同一ペイロード内で 3 つのレイヤーすべてに設定した値を返却します（明確化のため抜粋）：
```json highlight={4,10,20,27} theme={null}
{
"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` でも在庫レコードのフィールドとして現れます：
```json highlight={6,7} theme={null}
{
"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](/ja/webhooks#inventory-handling-complete) などの後続の在庫レイヤー Webhook で使用します。永続化したマッピングが、これらのイベントを正しい顧客注文へとルーティングします。
チャネル連携（Shopify、Loop）で作成された返品の場合、ステップ 1 はチャネルが返品を Return Helper にプッシュする処理で置き換わります。自動充当された SRN 値は [チャネル固有の挙動](#channel-specific-behaviour) を参照してください。ステップ 2〜4 は同じです。
### `markShipmentArrive` のバージョン
`markShipmentArrive` には 2 つのペイロード形態が存在します。**V202207 は新規アカウントのデフォルト** で、明示的に Return Helper のサポートへ V202407 への切替を依頼しない限り、お客様のアカウントはこのバージョンを受信します。
| バージョン | ペイロード形態 | 在庫の配信方式 |
| ------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| **V202207**（デフォルト） | バンドル — `shipment`、`returnRequest`、`returnInventoryList[]`、`lineItems[]`、`label` が同一イベントに同梱 | `returnInventoryList[]` 内にインライン |
| **V202407**（要望に応じて） | リーン — `shipment` オブジェクトのみ | ストリーミング — 在庫レコードごとに [`newInventoryCreated`](/ja/webhooks#inventory-created) イベントが続く |
両方とも同じライフサイクル・同じ最終状態を生み出します。違いは配信スタイルです：V202207 はすべての情報を 1 つの大きなペイロードにまとめて処理を 1 回で済ませ、V202407 はより軽量な `markShipmentArrive` の後に在庫イベントを個別配信します（ペイロードがコンパクトで、1 つの shipment が多数の在庫に分割される場合に適しています）。shipment が頻繁に多数の在庫を生成する場合（複数パッケージ、VAS 分割パーセル）は、サポートに V202407 の有効化を依頼してください。
同じワークフローの V202407 `markShipmentArrive` ペイロードは次のようになります：
```json highlight={7} theme={null}
{
"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 リファレンス](/ja/webhooks) を参照してください。