在庫転送Webhookに拠点IDが追加

8月 10, 2026

API CHANGE

在庫転送Webhookに
拠点ID(origin/destination)が追加

余計なAPI呼び出しゼロで転送元・先ロケーションを即判別 — 2026-07リリース予定

在庫転送系の6つのWebhookトピックのペイロードに origin.id と destination.id が新たに追加されました。これによりアプリ側は転送元・転送先のロケーションを追加APIコールなしで即座に特定できます。新フィールドは unstable APIバージョンで即時利用可能、パブリックリリースは 2026-07 を予定しています。

OVERVIEW

01変更内容：追加されたフィールドと対象トピック

新フィールドはLocation Global ID形式（gid://shopify/Location/数字）で返されます。旧APIバージョンのサブスクリプションや、転送元・先がロケーションでない場合（例: サプライヤーフルフィルメント）はキー自体がペイロードから省略されます（null返却ではありません）。

USE CASES

02業務に活かせるユースケース

課題: 複数倉庫・店舗間の在庫転送を監視するアプリで、Webhookを受信するたびに転送詳細APIを再呼び出しして転送元・先を取得していた。レート制限を圧迫しやすく、処理遅延が発生していた。
打ち手: 2026-07以降のAPIバージョンにWebhookサブスクリプションを更新し、ペイロードの origin.id / destination.id を直接参照してルーティングロジックを実装する。
効果: Webhook受信 → ロケーション特定のAPIコールが不要になり、処理ステップを削減。Admin APIのレート制限消費を抑えながらリアルタイム在庫監視を実現できる。
技術メモ: Global IDはそのままGraphQLクエリの引数として使用可能。gid://shopify/Location/123 の形式で location(id: $id) に渡せる。

課題: EC基幹システムと連携する際、在庫転送のWebhook受信後に「どの拠点からどの拠点へ」という情報をDBに記録する必要があり、毎回追加リクエストが発生していた。
打ち手: inventory_transfers/complete Webhookを受信した際に origin.id と destination.id をそのままERPや在庫DBへ書き込む処理を組み込む。
効果: 転送完了イベントの記録処理をシンプル化。基幹システムとのリアルタイム同期の信頼性が向上し、在庫差異の発生を防ぎやすくなる。
技術メモ: サプライヤーフルフィルメントなど拠点が存在しないケースでは origin / destination キー自体が存在しないため、コード側で key in payload チェックを入れること。

課題: 転送キャンセルイベント (inventory_transfers/cancel) 発生時に、どの拠点の在庫影響かをすぐ判断できず、在庫補正のオペレーションが後手に回っていた。
打ち手: キャンセルWebhookの origin.id を使って影響拠点を即特定し、在庫補正アラートを自動送信するワークフローを構築する。
効果: 転送キャンセル発生から在庫確認・補正指示までの時間を大幅短縮。オペレーションチームへの自動通知で人的ミスを削減できる。
技術メモ: inventory_transfers/cancel も新フィールド対象トピックに含まれているため、同じペイロード構造で処理できる。ただし対象APIバージョン (2026-07以降) でのサブスクリプション登録が前提。

DEV NOTES

03技術者が押さえるべきポイント

項目	詳細
対応APIバージョン	unstable で即時利用可能。パブリックリリースは 2026-07 予定。旧バージョンのサブスクリプションには新フィールドは含まれない。
フィールド省略の条件	旧APIバージョンのサブスクリプション、またはサプライヤーフルフィルメントのように転送元・先がロケーションでない場合、`origin` / `destination` キー自体がペイロードから省略される (`null` ではない)。
inventoryTransferSetItems の挙動明確化	ドキュメント記述が整理された（挙動変更なし）。渡したアイテムのみ追加・更新、渡さなかったアイテムは不変。READY_TO_SHIP / IN_PROGRESS 状態では `processableQuantity` のみ置換。DRAFTのみ quantity:0 が有効。
inventoryTransferRemoveItems の挙動明確化	ドキュメント記述が整理された（挙動変更なし）。空の `transferLineItemIds` はno-op扱いになり転送をそのまま返す。READY_TO_SHIP時に削除するとorigin拠点のavailable在庫に戻る。
エラーメッセージの改善	3つのユーザーエラー (`READY_TO_SHIP_TRANSFER_REQUIRES_AT_LEAST_ONE_ITEM` / `ALL_QUANTITY_SHIPPED` / `ITEM_PRESENT_ON_DRAFT_SHIPMENT_WITH_ZERO_QUANTITY`) のメッセージがより説明的になった。エラーコード自体は変更なし。既存のエラーハンドリングは影響を受けない。