Order オブジェクトに cartToken フィールドが追加

図解 ： Order オブジェクトに cartToken フィールドが追加（GraphQL Admin API） Admin GraphQL API / 2026-07 Order オブジェクトに cartToken フィールドが追加 注文を生成した「カート」に紐づくトークンを、GraphQL Admin API から直接取れるようになった。REST Admin API の cart_token と同じ値を返すフィールド。 このページの構成 何が変わったのか（30秒で理解） 仕組み図解 ： カートのトークンが注文に残る REST の cart_token と GraphQL の cartToken クエリの書き方（イメージ） 技術者が押さえるべき5つのポイント 業務に活かせる3つのユースケース 提案で使える1行サマリ 1 何が変わったのか GraphQL Admin API の Order オブジェクトに cartToken フィールドが追加された。 返ってくるのは「その注文を作る元になったカートのトークン」。これは REST Admin API に以前からある cart_token と 同じ値 。 これまで カートと注文を結ぶトークンは REST Admin API の cart_token でしか取れなかった。GraphQL に寄せていても、この値のためだけに REST を併用する必要があった。 これから Order.cartToken として GraphQL から直接取得できる。REST と同じ値なので、既存の突合ロジックをそのまま GraphQL 側へ移せる。 2 仕組み図解 ： カートのトークンが注文に残る cartToken の役割 ： 「どのカートがこの注文になったか」を結ぶ ID。カート段階で発行されたトークンが、注文成立後も Order 側に残る。これによりカート（購入前）と注文（購入後）を同じキーで紐づけられる。 3 REST の cart_token と GraphQL の cartToken 項目 REST Admin API GraphQL Admin API フィールド名 cart_token （snake_case） cartToken （camelCase） 載っている場所 Order リソース Order オブジェクト 返す値 同じ 注文を作ったカートのトークン 提供状況 以前から提供 新規追加 API バージョン 記載なし 変更ログのタグは 2026-07 トークンの形式・文字数、カート経由でない注文（手動作成・POS・ドラフト発の注文など）で値がどうなるか（null かどうか）は 変更ログに記載なし 。実装前に対象 API バージョンの公式リファレンスとサンドボックスで確認すること。 4 クエリの書き方（イメージ） 変更ログにクエリ例の記載はないため、以下は Order オブジェクトの新フィールドを取得する一般的な書き方のイメージ。実フィールド構成は対象バージョンのリファレンスで確認すること。 query { order (id: "gid://shopify/Order/123456789" ) { id name cartToken # ← 今回追加。REST の cart_token と同値 } } これまで cart_token を取るためだけに残していた REST 呼び出しを GraphQL に一本化できる。注文一覧取得と同じクエリに cartToken を 1 行足すだけで済む。 5 技術者が押さえるべき5つのポイント 1. 値は REST と完全に同一 cartToken は REST の cart_token と同じ値を返す。命名が camelCase になるだけで、突合ロジックや保存済みデータとの互換は保たれる。 2. バージョンは 2026-07 タグ 変更ログのタグは 2026-07 。利用するには対象バージョン以降を指定する必要がある。古いバージョン固定のアプリではまだ見えない可能性に注意。 3. REST 依存を一本化できる この値のためだけに REST を併用していたコードを GraphQL に寄せられる。デュアル API 構成を減らし、認証・レート制御を 1 系統に統一できる。 4. 非カート注文の挙動は未記載 手動作成・POS・ドラフト経由など「カートを経ない注文」で値がどうなるか（null になるか）は変更ログに 記載なし 。null 前提のハンドリングを入れておくのが安全。 5. カート（購入前）と注文（購入後）の橋渡しキー cartToken は「同一カート → 同一注文」を結ぶ共通キーとして使える。カート段階で蓄積したログ・行動データと、確定注文を後から JOIN する用途に向く。トークン自体は機密値ではないが、注文を一意に推測させ得る ID なのでログ出力時の取り扱いには配慮する。 6 業務に活かせる3つのユースケース USE CASE 1 カート放棄〜購入完了のファネルを GraphQL だけで突合 課題 カート段階の行動データと確定注文を結びたいが、結合キーになる cart_token を取るために REST を別系統で叩いていて、集計パイプラインが二重化していた。 打ち手 注文取得クエリに cartToken を追加し、カート側ログのトークンと JOIN。どのカートがどの注文になったかを GraphQL のレスポンスだけで再構成する。 効果 カート→購入の転換分析が単一 API で完結。放棄カート施策の効果測定が容易になる。 技術メモ 値は REST の cart_token と同一なので、既存の突合テーブルをそのまま使える。非カート注文では null になり得る前提でハンドリング。 USE CASE 2 REST → GraphQL 移行案件の「最後の REST 依存」を外す 課題 注文連携を GraphQL へ移行中だが、 cart_token だけ GraphQL に無く REST を残さざるを得ず、移行が完了しきれていなかった。 打ち手 注文クエリに cartToken を追加し、REST 呼び出しを廃止。認証・レート制御・エラーハンドリングを GraphQL 一系統に統一する。 効果 デュアル API の保守負担が減り、レート上限の管理がシンプルに。移行プロジェクトをクローズできる。 技術メモ 対象アプリの API バージョンを 2026-07 以降へ更新してから切替。古いバージョン固定のままだとフィールドが見えない。 USE CASE 3 外部 BI / データ基盤との注文ひも付けキーを統一 課題 GA4・自社 DWH・カート計測ツールで持っているカートトークンと、Shopify の注文を後から結合したいが、注文側のキーが GraphQL では取れなかった。 打ち手 注文同期バッチで cartToken も取得して保存し、外部基盤側のカートトークンと突合する共通キーにする。 効果 広告クリック〜カート〜注文を一貫した ID で追跡でき、アトリビューション精度が上がる。 技術メモ トークンは注文を一意に指し得る ID。BI 連携やログ転送の際は取り扱い範囲を決めておく。トークン形式は変更ログに記載がないため文字列として保持する。 7 提案で使える1行サマリ 「 注文を作ったカートのトークン（ cartToken ）が GraphQL Admin API の Order から直接取れる ように。 値は REST の cart_token と同一なので、 カート→注文の突合を GraphQL に一本化 でき、REST 併用を 1 つ減らせる。」 source ： shopify.dev/changelog/new-field-carttoken-added-to-the-order-graphql-admin-api Developer Changelog ／ 2026-05-12