Rollouts を「読める・追える」 クエリと Webhook が Admin GraphQL API に登場

図解 ： Admin GraphQL API で Rollouts の読み取りと Webhook 購読が可能に Admin GraphQL API / 開発者向け Rollouts を「読める・追える」 クエリと Webhook が Admin GraphQL API に登場 アプリが Rollout（計画的なローンチ・実験・期間限定イベント）を見つけ、スケジュールやトラフィック配分、変更されるリソースを読み取り、変更時には通知を受け取れるようになった。対象はディスカウント・カタログ・テーマ・チェックアウトとアカウントの設定。 このページの構成 そもそも何が変わるのか（30秒で理解） 図解 ： Rollout の中身と、読めるもの 新しく使える 4 つの機能 スケジュールと配分 ： 「設定値」と「実効値」は別物 Webhook → 再取得で追従する流れ アクセス条件（スコープと再承認） 技術者が押さえるべき5つのポイント 業務に活かせる3つのユースケース 提案で使える1行サマリ 1 そもそも何が変わるのか Rollout は、ディスカウント・カタログ・テーマ・チェックアウトとアカウントの設定などをまたぐ 「計画的なローンチ／実験／期間限定イベント」 の単位。 今回、アプリが Admin GraphQL API から Rollout を検索・取得して中身を読み 、 変化を Webhook で受け取れる ようになった。 アプリから見て ： これまで 本記事は以前の状態を明示していない（記載なし）。今回「アプリが Rollout を discover / read できるようになった」と案内されている。 アプリから見て ： これから Rollout の一覧・検索・ID 指定取得、トリートメントごとの変更内容、スケジュール、配分を読める。ライフサイクル・実効配分・リソース変更を Webhook で受け取れる。 2 図解 ： Rollout の中身と、読めるもの Rollout とは ： 記事では「ディスカウント・カタログ・テーマ・チェックアウトとアカウントの設定をまたぐ、計画的なローンチ・実験・期間限定イベント」と説明されている。マーチャント側の作成・運用方法の説明は本記事には記載なし。 3 新しく使える 4 つの機能 見つける・読む rollouts で一覧・検索 rollout(id:) で直接取得 何が変わるか トリートメントごとに 4 種のリソースへの影響 スケジュール・配分 開始/終了予定、設定配分 実効配分、split 値 最新に追従 Rollout Webhook を購読し 影響 Rollout を再取得 4 スケジュールと配分 ： 「設定値」と「実効値」は別物 ※ バーの長さはイメージ。具体的な数値や、両者がずれる条件は記事に記載なし。 記事は明確に 「設定された配分だけでは実効的なリーチは決まらない」 と注意している。実際にどれだけ届いているかを扱うなら effectiveTrafficAllocation を見ること。 5 Webhook → 再取得で追従する流れ 1 Rollout Webhook を購読 通知の種類は「ライフサイクル」「実効配分」「リソース変更」の 3 系統。 2 通知を受け取る どの Rollout が変わったかを知るきっかけとして使う。 3 影響 Rollout を再取得 記事の推奨 ： 影響を受けた Rollout を refetch して連携データを最新に保つ。 通知の系統 何がわかるか 具体的なトピック名 ライフサイクル Rollout の状態の変化 記載なし（API リファレンス参照） 実効配分 effective allocation の変化 記載なし（API リファレンス参照） リソース変更 Rollout が変更するリソースの変化 記載なし（API リファレンス参照） 6 アクセス条件（スコープと再承認） 必須 read_rollouts Rollout データにアクセスするために要求するスコープ。 併用 既存リソーススコープ Rollout の中に含まれるディスカウント等のリソース本体（payload）には、それぞれの既存スコープが適用される。 注意 再承認が必要な場合あり 既存インストールでは、マーチャントによる再承認（reauthorization）が必要になる可能性がある。 ディスカウントを読むアプリは、別ガイド 「Update your app to account for discount Rollouts」 に、ディスカウント固有の連携方法と互換性の挙動がまとまっている。対応 API バージョンは本記事に記載なし。 7 技術者が押さえるべき5つのポイント 1. 今回は「読み取り＋通知」 記事で案内されているのはクエリ（ rollouts / rollout(id:) ）と Webhook。Rollout を作成・更新する mutation については記載なし。 2. 設定配分 ≠ 実効リーチ trafficAllocation だけで判断しない。現在どれだけ効いているかは effectiveTrafficAllocation 、トリートメント間の配分は split 値で読む。 3. Webhook は「合図」、真実は再取得 記事は通知後に影響 Rollout を refetch するよう案内している。通知 payload の中身だけで状態を組み立てる前提にしない設計が無難。 4. スコープは二段構え read_rollouts に加え、中身のリソース payload には既存スコープが適用される。片方だけだと見えない部分が出る前提でスコープ設計とエラーハンドリングを。 5. ディスカウント系アプリは専用ガイドを必読 ディスカウントを読むアプリ向けに「Update your app to account for discount Rollouts」が用意され、 互換性の挙動 にも触れている。既存のディスカウント連携がある場合は、本機能の導入有無に関わらず確認対象。既存インストールの再承認フローもあわせて計画する。 8 業務に活かせる3つのユースケース USE CASE 1 ディスカウント連携アプリの「Rollout 由来の割引」への追従 課題 ディスカウントを読み取るアプリ（価格表示・レポート等）が、Rollout による期間限定・実験的な割引の存在を把握できないと、表示や集計がずれるおそれがある。 打ち手 read_rollouts を追加 → rollouts でディスカウントに影響する Rollout を把握 → Webhook 受信時に該当 Rollout を再取得。 効果 割引がいつ・どの配分で効くかをアプリ側でも把握でき、問い合わせや不整合の原因を追いやすくなる。 技術メモ ディスカウント固有の挙動は専用ガイドに従う。既存インストールは再承認が必要になる場合があるため、マーチャント向け告知を先に用意。 USE CASE 2 実験・ローンチの「実効リーチ」を可視化するダッシュボード 課題 テーマやチェックアウト設定の実験を行う際、「設定した配分」と「実際に届いている配分」の差が見えず、結果の解釈を誤りやすい。 打ち手 Rollout ごとに trafficAllocation ・ effectiveTrafficAllocation ・トリートメントの split 値・開始/終了予定を取得して並べて表示。実効配分の Webhook で更新。 効果 実験の進行状況を管理画面を巡回せずに一覧でき、レポート時の前提（実際の配分）を正しく添えられる。 技術メモ 記事が「設定配分だけでは実効リーチは決まらない」と明言している点を UI 上でも明示する。ずれる条件は記載なしのため推定ロジックは入れない。 USE CASE 3 セール・期間限定イベントの「変更カレンダー」と運用アラート 課題 ディスカウント・カタログ・テーマを同時に切り替えるイベントで、いつ何が変わるかが関係者間で共有されず、サポートや在庫・広告運用が後手に回る。 打ち手 Rollout の予定開始/終了時刻と、各トリートメントが影響するリソースを取得してカレンダー化。ライフサイクル / リソース変更 Webhook で Slack 等へ通知。 効果 イベント開始前の確認漏れ防止、切り替え時の問い合わせ対応の迅速化。 技術メモ 通知を受けたら必ず再取得して最新状態で表示を更新。具体的な Webhook トピック名や payload 形式は API リファレンスで確認（本記事に記載なし）。 9 提案で使える1行サマリ 「ディスカウント・カタログ・テーマ・チェックアウト設定をまたぐ Rollout を、 アプリが read_rollouts で読み、Webhook で追従できるようになった。 実際の配分は effectiveTrafficAllocation を見て、通知が来たら再取得するのが鉄則。」 source ： shopify.dev / changelog / read_rollouts Rollouts queries and webhooks in the Admin GraphQL API（2026-10-01 公開）