Checkout metafields が廃止 cart metafields / order metafields へ移行する

図解 ： Checkout metafields の廃止（API 2026-04）— cart / order metafields への移行 Action Required API 2026-04 Checkout metafields が廃止 cart metafields / order metafields へ移行する API バージョン 2026-04 で、checkout / customer account UI 拡張から checkout metafields の読み書きが「削除」された。古いバージョンで使っている拡張は 2026-04 へのアップグレードと移行が必須。 このページの構成 何が変わったのか（30秒で理解） 移行マップ図解 ： どこから・どこへ 2つの移行先（cart / order metafields） 新機能 ： cart → order の自動コピー Action Required ： やること（3ステップ） 技術者が押さえるべき5つのポイント 業務に活かせる3つのユースケース 提案で使える1行サマリ 1 何が変わったのか API バージョン 2026-04 をもって、 checkout / customer account UI 拡張から checkout metafields を読み書きする機能が削除 された。 代わりに、 Checkout UI 拡張では cart metafields 、 Customer Account UI 拡張では order metafields を使う。 削除されたもの checkout / customer account UI 拡張での checkout metafields の読み取り・書き込み。2026-04 では使えない。 Checkout UI 拡張の移行先 cart metafields に置き換える。チェックアウト中のデータ保持はこちら。 Customer Account UI 拡張の移行先 order metafields に置き換える。注文後・アカウント画面のデータ参照はこちら。 これは非推奨（deprecation）の予告ではなく 「削除済み（removed）」 。古いバージョンのまま 2026-04 へ上げると checkout metafields 依存箇所が動かなくなるため、上げる前に移行を済ませること。 2 移行マップ図解 ： どこから・どこへ ポイントは「 拡張の種類で移行先が違う 」こと。チェックアウト側は cart、注文後のアカウント側は order。さらに、cart に入れた値は注文作成時に order へ自動で引き継げる（次節）。 3 2つの移行先（cart / order metafields） 項目 cart metafields order metafields 使う拡張 Checkout UI 拡張 Customer Account UI 拡張 主な役割 チェックアウト進行中のデータ保持・読み書き 注文に紐づくデータの参照・読み書き 旧 checkout metafields との関係 Checkout UI 拡張での代替 Customer Account UI 拡張での代替 公式移行ガイド 「Migrate to cart metafields in checkout UI extensions」 「Migrate to order metafields in customer account UI extensions」 各 metafield の具体的な API スキーマ・コード差分は、本チェンジログ本文には 記載なし 。上記 2 本の公式移行ガイドを参照のこと。 4 新機能 ： cart → order の自動コピー order metafield 定義に 新しい機能 が追加された ： 注文作成時（order creation）に、cart metafields の値を order metafields へ自動でコピー できる。cart と order をまたぐデータ管理を簡素化する。 ① cart に値を保持 Checkout UI 拡張が cart metafields に書き込む。 ② 注文作成で自動複写 order metafield 定義の設定により、値が order 側へ自動コピーされる。 ③ order で参照 Customer Account UI 拡張や注文データ側で order metafields として扱える。 これにより「チェックアウトで集めた情報を、注文後の画面でも使う」というよくあるパターンを、 手動でのデータ受け渡しを書かずに 実現できる。コピーの発火タイミングは 注文作成時 。 5 Action Required ： やること（3ステップ） 1 依存箇所を棚卸し checkout / customer account UI 拡張で checkout metafields を読み書きしている箇所を洗い出す。 2 移行ガイドに沿って置換 Checkout UI 拡張 → cart metafields、Customer Account UI 拡張 → order metafields に書き換える。 3 API 2026-04 へ上げる 移行後に拡張を 2026-04 へアップグレード。古いバージョンを使い続けている場合は必須。 順序が重要 ： 「移行 → アップグレード」 。checkout metafields は 2026-04 で既に削除済みのため、移行せずにバージョンだけ上げると該当機能が壊れる。 6 技術者が押さえるべき5つのポイント 1. 「非推奨」ではなく「削除済み」 2026-04 で checkout metafields の読み書きは既に削除。猶予を当て込んだ先送りは不可。バージョンアップ前に移行を完了させる。 2. 移行先は拡張の種類で分岐 Checkout UI → cart metafields、Customer Account UI → order metafields。同じ「checkout metafields」でも置換先が 2 系統に分かれる点に注意。 3. cart→order の自動コピーを設計に組み込む order metafield 定義の新機能で、注文作成時に cart の値を order へ自動複写できる。受け渡しコードの自作を減らせる。 4. 公式移行ガイドが正本 cart 用・order 用の 2 本の移行ガイドが用意されている。具体的な API 仕様・コード差分は本文に記載なしのため、ガイドを参照する。 5. データの「責任範囲」を cart / order で再整理 チェックアウト中に必要なデータは cart、注文確定後に残すべきデータは order、という役割分担で設計し直すと自然に収まる。両方で必要なものは「cart に書いて注文作成時に order へ自動コピー」が定石パターンになる。 7 業務に活かせる3つのユースケース USE CASE 1 既存ストアの「checkout metafields 棚卸し → 計画移行」 課題 古い API バージョンの checkout / customer account UI 拡張が checkout metafields に依存しており、2026-04 へ上げると壊れる。 打ち手 依存箇所を全件リスト化し、Checkout UI 拡張は cart metafields、Customer Account UI 拡張は order metafields へ計画的に置換してからアップグレード。 効果 サポート切れ・本番障害を回避し、最新 API での保守性を確保。 技術メモ 移行 → 2026-04 アップグレードの順序を守る。具体手順は公式の 2 本の移行ガイドに準拠。 USE CASE 2 「チェックアウトで集めた情報」を注文後画面まで自動連携 課題 ギフトメッセージ・配送希望・同意フラグ等をチェックアウトで集め、注文後のアカウント画面でも表示したいが、データ受け渡しを自前で実装していた。 打ち手 cart metafields に書き込み、order metafield 定義の自動コピーで注文作成時に order へ複写。Customer Account UI 拡張は order metafields を参照。 効果 受け渡しロジックの自作が不要になり、データ不整合のリスクと実装工数を削減。 技術メモ コピー発火は注文作成時。注文作成後に変わる値は対象外の前提で設計する。 USE CASE 3 受託・パートナーの「2026-04 対応案件」テンプレ化 課題 複数クライアントの拡張が checkout metafields を使っており、案件ごとに調査・移行を都度やると非効率。 打ち手 「依存検出 → cart/order への置換 → 自動コピー設定 → 2026-04 アップグレード」を標準チェックリスト化して横展開。 効果 移行案件の見積もり・品質を平準化し、納期短縮と取りこぼし防止。 技術メモ 拡張の種類（Checkout UI / Customer Account UI）で移行先が分岐する点をチェックリストの分岐条件にする。 8 提案で使える1行サマリ 「API 2026-04 で checkout metafields は削除済み 。Checkout UI 拡張は cart metafields 、Customer Account UI 拡張は order metafields へ要移行。 さらに 注文作成時に cart→order を自動コピー できるようになり、データ連携の自作実装を減らせる。 対応順は『移行してから 2026-04 へ上げる』が鉄則。」 source ： shopify.dev / changelog / deprecation-of-checkout-metafields-in-checkout-and-customer-account-ui-extensions Shopify Developer Changelog ・ 公開 2026-04-01