OrdersウェブフックにsellingPlanID追加

11月 03, 2026

WEBHOOKS

Ordersウェブフックにselling_plan_idが追加

API 2026-10以降、サブスクリプション情報をウェブフック1回で取得可能に

このアップデートはサブスクリプション対応アプリを開発・運用している開発者が対象です。API バージョン 2026-10 以降から、Ordersウェブフックのline itemsペイロードにselling_plan_idフィールドが自動的に含まれるようになります。これによりサブスクリプションのプランIDを得るための追加APIコールが不要になり、処理効率が改善します。

1変更内容：Before / After

2ペイロード構造

Ordersウェブフック内 line_items の新フィールド

サブスクリプション対象外のline itemでは selling_plan_id は null になります

3業務に活かせる具体ユースケース

課題: サブスクリプション注文を受信するたびにAdmin APIを呼び出してプランIDを取得しており、大量注文時にAPIレート制限に抵触するリスクがあった
打ち手: ウェブフックハンドラー内で line_items[n].selling_plan_id を直接参照し、プランIDに基づく分岐処理をAPIコールなしで完結させる
効果: 注文件数が多い繁忙期でもAPIコール数を削減でき、レート制限エラーによる処理失敗リスクを低減できる
技術メモ: ウェブフックのAPIバージョンを 2026-10 以上に設定する必要あり。既存バージョンのウェブフックエンドポイントはフィールドが含まれないため要バージョン確認

課題: サブスクリプションと通常購入が混在する注文を受け取った際、どのline itemがサブスクかを判別するロジックが複雑になっていた
打ち手: selling_plan_id が null かどうかを確認するだけでサブスク判別が可能。通常購入は null、サブスクリプションは具体的なIDが入る
効果: 判定ロジックがシンプルになり、コードの可読性と保守性が向上する
技術メモ: 値がnullの場合は非サブスクアイテムと明確に定義されているため、undefined チェックではなく null チェックを実装すること

課題: サブスクリプションプランごとに異なる倉庫フローや配送スケジュールをトリガーしたいが、プランID取得のレイテンシがボトルネックになっていた
打ち手: ウェブフック受信と同時に selling_plan_id を取得できるため、注文受信→プラン判定→フルフィルメント振り分けを1つのウェブフックハンドラー内で完結させる
効果: フルフィルメント開始までのリードタイムを短縮でき、サブスク会員への即時出荷体験を実現しやすくなる
技術メモ: selling_plan_idはShopifyのSellingPlanオブジェクトのIDと対応。詳細なプラン情報（請求間隔等）が必要な場合はAdmin APIへの別途参照は引き続き必要

4技術者目線のポイント

観点	詳細
対象APIバージョン	2026-10 以降。それ以前のバージョンには影響なし（フィールドが存在しない）
移行要否	既存アプリへの影響なし・アクション不要。新フィールドを活用したい場合はウェブフックのAPIバージョンを 2026-10 に更新する
null の扱い	サブスクリプション対象外のline itemでは `selling_plan_id` は `null`。非nullチェックでサブスク判別が可能
対象ウェブフック	Orders系ウェブフック（orders/created、orders/updated 等）のline itemsが対象。詳細は公式のorders webhooks referenceを参照
詳細プラン情報	selling_plan_id 単体で得られるのはIDのみ。プラン名・請求間隔などの詳細属性はAdmin APIへの別途クエリが必要（元記事に記載なし）