チェックアウトメタフィールド廃止
API 2026-04 移行ガイド
旧APIを使い続けると読み書きが完全停止。今すぐ移行計画を立てよう
API バージョン 2026-04 より、チェックアウトおよびカスタマーアカウントUI拡張における「チェックアウトメタフィールド」の読み書きが完全に削除されました。旧APIバージョンを継続使用しているストアは、チェックアウトUI拡張ではカートメタフィールドへ、カスタマーアカウントUI拡張ではオーダーメタフィールドへ早急に移行する必要があります。
1何が変わったか — Before / After 図解
2業務に活かせる具体ユースケース
- 課題
- チェックアウト画面でギフトメッセージや配送希望日を顧客に入力させ、そのデータをチェックアウトメタフィールドで保持していたカスタムUIがある
- 打ち手
- チェックアウトUI拡張を cart.metafields に書き換える。公式の「Migrate to cart metafields in checkout UI extensions」ガイドに沿ってAPIバージョンを 2026-04 に更新し、参照先を変更する
- 効果
- 移行後もギフトメッセージ・配送希望日の収集フローを維持でき、かつカート単位で値が管理されるため、ゲスト購入でも安定して動作する
- 技術メモ
- cart.metafields への書き込みには metafield definition の設定が必要。ownerType: CART を指定すること
- 課題
- カスタマーアカウントページで購入後の注文詳細にカスタム情報（例: 業務用途区分や会員ランク特典フラグ）を表示するUI拡張が、チェックアウトメタフィールドを参照していた
- 打ち手
- カスタマーアカウントUI拡張を order.metafields へ移行する。「Migrate to order metafields in customer account UI extensions」ガイドを参照し、APIバージョンと参照オブジェクトを更新する
- 効果
- 注文に直接紐づく形でカスタムデータを管理できるため、注文履歴ページでの情報表示がより整合的になり、後工程での参照もしやすくなる
- 技術メモ
- order metafield definition で新設された「カートメタフィールドから自動コピー」機能を活用すると、注文作成時の値引き継ぎをコードレスで実現できる
- 課題
- カートで収集したB2B向け注文コード（発注番号など）をチェックアウト経由でオーダーに引き継ぐフローを構築していたが、移行後にデータが途切れる懸念がある
- 打ち手
- cart.metafields に発注番号を書き込み、order metafield definition の自動コピー機能を有効化する。これにより注文作成と同時にオーダーメタフィールドへ値が転写される
- 効果
- カスタムコードなしでカート→オーダーへのデータ引き継ぎが完結し、バックエンド連携やCSVエクスポートの際にも注文単位でカスタムデータを参照できる
- 技術メモ
- 自動コピー機能は order metafield definitions に追加された新しい capability として提供されている。詳細は元記事リンク先のドキュメントで確認すること
3技術者目線の重要ポイント
2026-04 以降で checkout metafields の読み書きが完全削除。旧バージョンのAPIを使っている拡張はすぐに影響を受ける。バージョンを固定していた場合でも、Shopifyのバージョン廃止スケジュールに注意が必要。
checkout.metafields → cart.metafields へ変更。ownerType が CART のメタフィールド定義を事前に作成しておく必要がある。公式移行ガイドに手順が記載されている。
checkout.metafields → order.metafields へ変更。注文オブジェクトに紐づくため、注文作成後にのみアクセス可能な点に設計上の注意が必要。
order metafield definition に、カートメタフィールドの値を注文作成時に自動コピーする新しい機能が追加された。カスタムWebhookやFunctionを書かずにデータ引き継ぎが可能になる。
サードパーティ製アプリがチェックアウトUI拡張を提供している場合、アプリ開発者側の対応状況を確認すること。自社カスタム拡張がある場合は、コードベースの全文検索で checkout.metafields の参照箇所を洗い出すことを推奨。
| 拡張タイプ | 旧オブジェクト | 新オブジェクト | 移行ガイド |
|---|---|---|---|
| チェックアウトUI拡張 | checkout.metafields |
cart.metafields |
公式: Migrate to cart metafields |
| カスタマーアカウントUI拡張 | checkout.metafields |
order.metafields |
公式: Migrate to order metafields |
| 自動コピー機能 | 記載なし | order metafield definition | Learn more リンク参照 |
| 対応APIバージョン | 〜2026-01 | 2026-04〜 | — |
チェックアウトメタフィールドの廃止はAPI 2026-04からの破壊的変更であり、カートメタフィールド・オーダーメタフィールドへの移行と、新しい自動コピー機能の活用によって、より堅牢なデータ管理フローを構築できます。
Source: https://shopify.dev/changelog/deprecation-of-checkout-metafields-in-checkout-and-customer-account-ui-extensions | 公開日: 2026年4月27日 ※本記事はShopify公式ではなく独立系メディアによる解説です。最新情報・正確な仕様は必ず公式ドキュメントでご確認ください。
Share:
GraphQL LineItemに割引後・税前小計フィールド追加
POSでスキャン可能な割引コードQRコード対応