ドメイン用語は有用な箇所では実際のワイヤフォーマット（例：
returnInventoryId、labelGenerated）でコードスパンに記載しています。本用語集で挙げる Webhook イベント名や schema フィールド名は、API が実際に発行・受理する名称と完全に一致します。倉庫到着前
Return Shipment
API で作成する到着前オブジェクトで、ある荷物が Return Helper の倉庫に向かっていることを宣言します。service type、出荷元住所、parcel の寸法、items リスト、申告総額を保持します。shipmentId で識別されます。
- 作成：Create Return Shipment
- リスト（履歴バックフィル用）：List Shipments
- Schema：
CreateReturnShipmentRequest
Label
Return Shipment に対して生成される配送ラベル。生成は非同期です — 配送作成 API 呼び出しはラベル要求をキューに積み、labelRequestStatusCode: queued を返します。実際のラベル URL は後で Webhook 経由で届きます。
- Webhook：Label result（
category: labelGenerated/action: labelGenerated） - 主なフィールド：
labelUrl、trackingNumber、shipmentId（突合には必ずshipmentIdを使い、labelIdは使わないでください）
RMA（Return Merchandise Authorization）
荷物が到着した時点で倉庫が割り当てるグローバル一意な識別子。tracking number はキャリア間または同一キャリア内で衝突しうるうえ、VAS によって 1 つの荷物が複数の RMA に分割されることもあるため、Return Helper は tracking number ではなく RMA を主要な連絡識別子としています。- フォーマット：
<倉庫プレフィックス>-<倉庫 ID>-<YYMMDD>-<環境文字><連番>-<チェック桁>（分割荷物には 2 桁の分割連番が追加） - Webhook：RMA updated（
category: notifyUserRmaSwapped） - 詳細：Getting Started → RMA
Custom Field Map
Return Shipment に付与できる任意のキー・バリュー metadata。Return Helper はそのまま保持し、関連する Webhook イベントで返却します。1 つの return につき最大 24 件。- フィールド：Return Shipment、parcel item、複数の Webhook payload 上の
customFieldMap
倉庫到着
Return Inventory
荷物が受領・処理された後に倉庫が作成する到着後オブジェクト。returnInventoryId で識別されます。1 件の Return Shipment が複数の Return Inventory レコードを生むことがあります（荷物単位または line item 単位、状況による）。
- 取得：Get Return Inventory Details
- リスト（履歴バックフィル用）：List Return Inventories
- Webhook：Inventory created（
category: newInventoryCreated）
Unknown Shipment
セラーが作成した Return Shipment と紐付かない状態で倉庫に到着し、後にあるセラーのものと識別された荷物。割当が完了すると Return Inventory としてアカウントに流れ込みます。- Webhook：Unknown shipment assigned（
category: rsl/action: assignUnknown） - Payload に含まれるもの：
returnInventoryId、shipmentId、returnRequestId、および割当前に撮影された在庫画像
Inventory Image
倉庫で撮影された、荷物の内容と状態を示す写真。倉庫が画像を追加・差替え・削除するたびに、URL リストが Webhook で配信されます。- Webhook：Image updated（
category: rrli/action: changeLineItemImage）
Warehouse Arrival Event
倉庫が荷物を受領済みとしてマークした瞬間。Webhook で配信され、これが「荷物が到着した」ことを示す正式なシグナルです。- Webhook：Warehouse shipment arrived (v2)（
category: rsl/action: markShipmentArrive）
到着後の処理
Handling Instruction
到着後の Return Inventory をどう扱うか倉庫に伝える指示。利用可能な handling type は Dispose、On-hold、Resend、Recall、VAS（以下定義）。- 更新：Update Return Inventory Handling
- キャンセル：Cancel Return Inventory Handling
- Webhook：Inventory handling complete（
category: rinv/action: completeInventoryHandling）
Dispose
倉庫が在庫を破棄／廃棄します。標準の handling instruction で dispose handling code を指定して発行します。On-hold
倉庫が在庫を一時的に保管し、処理を進めません。判断に時間が必要なときに使用します。標準の handling instruction で on-hold handling code を指定して発行します。Resend
倉庫が在庫を新しい宛先（通常は別の購入者）に再発送します。1 つ以上のreturnInventoryId を参照する独立したオブジェクトとして作成されます。
- 作成：Create Resend Order
- キャンセル：Cancel Resend Order
- Webhook：Resend status update（
category: resend/action: updateResendStatus）
Recall
倉庫が在庫を Return Helper の香港集約倉庫に送り、集中処理します。1 回の呼び出しで最大 100 件のreturnInventoryId を指定できます。指定の宛先に在庫を一括で送りたい場合は、代わりに Consolidate Shipping Order を使用してください。
- 作成：Create Recall by Return Inventory IDs
- Webhook：Recall status update（
category: recall/action: recallUpdateStatus）
VAS（Value-Added Services）
倉庫が在庫に対して行う一連の作業群 — 例えば 1 件の在庫を複数のアイテムに分割する、再梱包する、商品検品を行うなど。VAS が在庫を分割した場合、分割後の各ピースはそれぞれ自分の RMA を持ちます。- 作成：Create VAS by Return Inventory ID
- Webhook（完了）：VAS update（
category: rrliv/action: vasUpdated） - Webhook（分割）：Split line item（
category: lineItemVasReturnInventoryLineItem/action: splitLineItem）
FBA（Fulfilled by Amazon）
FBA Shipment
FBA 対応商品の後続処理（restock、replenish、recall、dispose 等）のために Return Helper 倉庫へ送る配送。fbaShipmentId で識別されます。
- 作成：Create FBA Shipment
- リスト（履歴バックフィル用）：List FBA Shipments
FBA Instruction
倉庫にある FBA 在庫に対する指示 — restock、replenish、recall、dispose、または “others”。returnInventoryId ではなく FNSKU + 数量で発行します。
- 作成：Create FBA Instructions
- リスト（履歴バックフィル用）：List FBA Instructions
FNSKU
Amazon の商品別 fulfillment SKU。FBA 在庫を扱うあらゆる場所でreturnInventoryId の代わりに使用します。
Consolidate Shipping
Consolidate Shipping Order
複数の Return Inventory レコードをまとめて 1 セットの外向け荷物として発送する集約配送。在庫をセラーへ送り返す際の配送コスト削減に使います。- 作成：Create Consolidate Shipping Order
- 確定：Confirm Consolidate Shipping Order
- Webhook（コスト）：Consolidate shipping cost updated
- Webhook（完了）：Consolidate order completed
認証と連携基盤
API Key と API Token
サーバーが認証を要する各リクエストでx-rr-apikey および x-rr-apitoken ヘッダーとして送信する 2 つの認証情報。User Portal の Settings → Signing Key and API Token で発行されます。
Signing Key
Return Helper が Webhook リクエストの署名に使用する Base64 エンコードされた共有秘密鍵。受信側はこれを使って生 body に対してreturnhelper-signature ヘッダーを検証します。User Portal で API key と同じ画面で発行されます。
Webhook / Notification
Return Helper が非同期イベント（ラベル結果、倉庫イベント、handling 完了など）をお客様のサーバーへ配信する仕組み。署名付き body の HTTPS POST として配信されます。Webhook が標準のデータ交換チャネルで、list エンドポイントは一度限りのバックフィル用です。- 詳細：Webhooks
Idempotency Key
状態を変更する各リクエストに対して生成する一意の値で、x-returnhelper-idempotency-key ヘッダーで送信します。Return Helper は同一 key のリトライを重複排除し、ネットワークリトライによる重複した shipment / resend / recall / VAS / FBA shipment の発生を防ぎます。