Analytics指標ターゲットをGraphQL APIで管理

8月 14, 2026

ANALYTICS API

Analytics指標ターゲットをGraphQL APIで管理できるようになりました

売上目標の設定・追跡をアプリから自動化。Shopify管理画面と同一APIで一元管理

このAPIはアプリ開発者を対象に2026年4月29日より利用可能になりました。4つの新しいGraphQLオペレーションにより、Shopify管理画面と同じ基盤を使って指標ターゲットの作成・管理をアプリから完全にプログラムで行えます。

1追加された4つのGraphQLオペレーション

2ターゲットのデータ構造と主要ルール

フィールド/概念	内容	備考
metric	対象となる分析指標	例: 総売上など
amount	目標値（数値）	例: 50,000ドル
time period	対象期間	例: 今四半期
filter（任意）	販売チャネルや商品などの絞り込み	ShopifyQL の WHERE 句、= または IN 演算子。1ターゲットにつき1フィルターのみ
status（自動算出）	In progress / Achieved / Not achieved / Upcoming	クエリ時に期間と現在値から自動導出
重複排除	指標・日付範囲・フィルターの組み合わせで一意識別	重複作成時はuserErrorが返る

3業務ユースケース

課題: 過去の販売実績や業界ベンチマークをもとに現実的な目標を設定したいが、マーチャントが手動で入力する手間がかかる
打ち手: analyticsTargetCreate を使い、過去データの分析結果からスマートデフォルト値を自動でターゲットとして書き込むゴール設定アプリを構築する
効果: マーチャントは自分のShopify Analytics画面に自動生成された目標ゲージが表示され、即座に進捗を可視化できる
技術メモ: write_reports スコープが必要。重複検知のためにcreate前にanalyticsTargetsで既存一覧を照合することを推奨

課題: 社内BIツールやカスタムダッシュボードにShopifyの目標進捗を表示したいが、APIがなく管理画面の数値と乖離が生じていた
打ち手: analyticsTargets クエリでターゲット一覧と自動算出済みのstatusを取得し、外部ダッシュボードに組み込む
効果: Shopify管理画面と全く同じ目標値・ステータスを自社BIに反映でき、データの一貫性を担保できる
技術メモ: read_reports スコープのみで読取可能。ページネーション対応のため大量ターゲットも漏れなく取得できる

課題: 代理店として複数クライアントストアの売上目標を一括設定・進捗モニタリングしたい
打ち手: エージェンシーダッシュボードから各ストアに analyticsTargetCreate / analyticsTargetUpdate を実行し、analyticsTargets でステータスを定期ポーリングして一元管理する
効果: クライアントごとに管理画面を開かずに目標設定と進捗確認を自動化でき、運用コストを大幅削減できる
技術メモ: 削除は復元不可のため analyticsTargetsDelete は慎重に使用。各ストアの install 時に read_reports・write_reports の両スコープを要求すること

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

🔑 必要なスコープ

読み取りのみは read_reports、作成・更新・削除には write_reports が必要。両方要求しておくと汎用的。

🔁 重複作成への対処

同じ「指標 + 日付範囲 + フィルター」の組み合わせは1つのみ許容。重複時は userError が返るため、create前に一覧取得でチェックするのがベストプラクティス。

📊 ステータスは自動算出

status フィールド (In progress / Achieved / Not achieved / Upcoming) はAPIがクエリ実行時に期間と現在の指標値から自動で導出。開発者側での計算は不要。

🗑️ 削除は不可逆

analyticsTargetsDelete で削除したターゲットは復元不可。誤削除防止のため、削除前に確認UIを設けることを強く推奨。

🏷️ ColumnDataType 新値 (2026-04)

UNITLESS_SCALAR（CLS パーセンタイルなど単位なし指標）と MULTIPLIER（ROAS など倍率指標）が追加。以前は FLOAT だったため、2026-04以降のバージョンを使うアプリはパーサー修正が必要な場合あり。2026-04より前のAPIバージョン呼び出しは影響なし。