marketingEngagementCreate
isCumulative 引数 廃止
累積エンゲージメント送信から非累積形式へ — 今すぐ移行を
ShopifyはmarketingEngagementCreateミューテーションのisCumulative引数を廃止予定とし、デフォルト値をfalseに変更します。累積メトリクスを送信しているすべてのマーケティングインテグレーションは、非累積(差分)形式への移行が必要です。既存のアクティビティはいつでも移行できます。
01変更内容：累積から非累積へ
「累積値」とは、計測開始からの合計数を毎回送る方式。「非累積(差分)値」とは、前回送信からの増分のみを送る方式です。Shopifyは今後、差分値のみを受け付けるよう仕様を統一します。
USE CASES02業務に活かせる具体ユースケース
- 課題
- 既存のメールマーケティングアプリが、キャンペーン開始から累積クリック数をまとめてAPIに送信していた
- 打ち手
- 各送信バッチで「前回値との差分」を計算し、
isCumulative: false（またはフィールド省略）で送信するよう処理を変更する - 効果
- Shopifyのマーケティング分析ダッシュボードでの二重計上リスクを排除し、正確なエンゲージメント集計が可能になる
- 技術メモ
- 差分計算ロジックをアプリ側で保持する必要がある。前回送信値をDBやKVSに記録しておくことを推奨
- 課題
- 広告プラットフォーム連携アプリが、インプレッション数・クリック数を累積値でShopifyに同期していた
- 打ち手
- プラットフォームAPIから取得するレスポンスが累積値の場合、直前取得値との差分を算出してから
marketingEngagementCreateに渡すアダプター層を実装する - 効果
- 期間別のパフォーマンスレポートが正確になり、Shopify Analyticsとの整合性が向上する
- 技術メモ
- プラットフォームによっては差分値を直接取得できるAPIエンドポイントが存在する場合もあるため、仕様を再確認することを推奨
- 課題
- 新規にマーケティングアプリを開発する際に、isCumulative引数の扱いを誤りそう
- 打ち手
- 新規実装では
isCumulative引数を省略するか、明示的にfalseを渡す設計にする。廃止予定の引数はコードレビューチェックリストに追加する - 効果
- 将来の完全廃止後も動作し続ける堅牢なインテグレーションを最初から構築できる
- 技術メモ
- 引数を省略してもデフォルト
falseが適用されるため、省略する書き方が最もシンプルで将来互換性が高い
03技術者向けポイント
対象ミューテーション: marketingEngagementCreate。引数は廃止予定(Deprecated)となり、デフォルト値はfalse固定になります。
公式には「いつでも移行可能」と明記されています。完全廃止の時期は元記事に記載なし。早期移行を推奨します。
ミューテーション自体は引き続き使用可能。isCumulative引数を除去するかfalseに変更するだけで対応完了です。
移行前後で同一期間のデータが重複カウントされないよう、移行タイミングの境界値を慎重に設計してください。移行日のデータ取り扱いを明確に定義することが重要です。
自社・受託アプリでisCumulative: trueを明示的に渡している箇所をコード検索で洗い出し、優先度をつけて対応しましょう。
| 確認項目 | 内容 | 状態 |
|---|---|---|
| isCumulative: true の使用箇所 | コード全体をgrep/検索で洗い出す | 要対応 |
| 差分計算ロジックの実装 | アプリ側で前回値を保持し差分を算出 | 設計必要 |
| isCumulative: false または省略 | 新規実装・修正済み箇所に適用 | 推奨 |
| 移行境界値の定義 | 移行日のデータ重複防止 | 要確認 |
| 完全廃止スケジュール | 公式発表を待つ（元記事に記載なし） | 記載なし |
「マーケティングエンゲージメントAPIの非累積移行対応で、Shopify Analyticsの集計精度を確保しましょう。」
Source: https://shopify.dev/changelog/deprecation-of-cumulative-marketing-engagements | 公開日: 2026年7月1日
Share:
下書き注文の頭金フィールドがGraphQL APIに対応