「今四半期で総売上 $50K」のような数値目標（メトリクス目標）を、4 つの新オペレーションでアプリから作成・取得・更新・削除できるようになった。管理画面のマーチャントが見るのと同じ目標を、同じ API・同じルール・同じバリデーションで扱える。
目標の設定・進捗確認は Shopify 管理画面の Analytics 内で完結。外部の目標設定ツールや BI ツールからは触れなかった。
アプリが目標を読み書きでき、アプリが作った目標もマーチャントが作った目標と並んで管理画面・ダッシュボードのゲージに表示される。
analyticsTargetCreateメトリクス・目標値・期間・任意のフィルタ（例 ： 特定の販売チャネルや商品に限定）を指定して作成。
analyticsTargetsショップの目標を取得。ページネーションに対応。
analyticsTargetUpdateメトリクス・名前・目標値・期間・フィルタを変更できる。
analyticsTargetsDelete目標を削除。削除した目標は復元できない。
analyticsTargetsDelete は名前が複数形（targets）。削除は不可逆なので、UI 上で確認ステップを挟む実装が安全。| 項目 | 内容 |
|---|---|
| スコープ | read_reports と write_reports の権限が必要。 |
| 重複排除 | 目標は メトリクス・期間（date range）・フィルタの組み合わせで一意に識別される。重複作成を試みると、必要な変更を案内する userError が返る。 |
| ステータス計算 | クエリ時点の期間と現在のメトリクス値から、status フィールド（In progress / Achieved / Not achieved / Upcoming）を API が自動で導出する。 |
| フィルタ | 各目標は ShopifyQL の WHERE 句に ディメンションベースのフィルタを 1 つ持てる。演算子は = または IN。 |
status は保存値ではなく、クエリ時点の「期間」と「現在のメトリクス値」から毎回導出される。アプリ側でステータスを計算・保持する必要はない。
API バージョン 2026-04 で、ShopifyqlTableDataColumn の ColumnDataType に 2 つの値が追加された。これまで FLOAT を返していたメトリクスが対象。2026-04 より前のバージョンを使う呼び出し元には影響しない。
UNITLESS_SCALAR単位を持たない無次元のスコア値。Web パフォーマンス指標に適用 ： p50_cls / p75_cls / p90_cls / p99_cls（Cumulative Layout Shift のパーセンタイル）。
MULTIPLIER比率・倍率を表す値（例 ： 3.2x）。shop_campaign_return_on_ad_spend（広告費用対効果 / ROAS）に適用。
FLOAT 前提でパースしているコードは、2026-04 へ上げる際に UNITLESS_SCALAR / MULTIPLIER のハンドリング追加が必要。表示フォーマット（"3.2x" 等）も合わせて見直す。読み取りでも read_reports、作成・更新・削除には write_reports が要る。アプリのアクセススコープ申請に忘れず含める。
「メトリクス × 期間 × フィルタ」で重複判定。同一キーの作成は userError。同期処理は「無ければ作る／有れば更新」に倒すと衝突しない。
In progress / Achieved / Not achieved / Upcoming はクエリ時に自動導出。自前で計算・保存しない。期間や値が動けば自然に切り替わる。
ShopifyQL の WHERE に持てるディメンションフィルタは 1 つだけ。複数条件の AND は不可。販売チャネル別や商品別の目標は、目標を分けて作る。
アプリが作った目標も Targets 一覧・ダッシュボードに同じゲージで出て、マーチャントが直接編集・削除できる。アプリ外で勝手に上書きされうる前提で、同期は冪等かつ差分検出できる設計にしておく。analyticsTargets はページネーション対応なので全件走査も可能。
analyticsTargetCreate でスマートな初期目標を自動作成。期間・メトリクスもまとめて提案。analyticsTargetUpdate に倒し、userError を避ける。analyticsTargets でマーチャントの目標を読み取り、自社グラフに進捗・達成状況を重ねて表示。status は API が自動導出するので、自前計算せずそのまま使う。件数が多い店舗はページネーションで全件取得。analyticsTargets を横断で取得し、未達（Not achieved）の店舗を集約表示。read_reports / write_reports の付与が前提。削除は不可逆なので、店舗横断の一括 analyticsTargetsDelete は確認フローを必須に。