Customer Account APIでメタフィールド定義が必須に

8月 08, 2026

API CHANGE

Customer Account API
メタフィールド定義が必須化

定義なしのアプリメタフィールドは値を返さなくなりました

OVERVIEW

01この変更の概要

2026年6月16日より、Customer Account APIでアプリリソースのメタフィールドを取得するには、メタフィールド定義（Definition）の作成と顧客アカウントAPIアクセス権限の設定が必須になりました。定義が存在しないアプリメタフィールドはAPIから値が返らなくなります。Customer・Orderリソース所有のメタフィールドは今回の変更対象外です。対応が必要なのは、アプリが所有するメタフィールドをCustomer Account UI拡張・Hydrogen・Headlessストアで利用している開発者です。

MECHANISM

02仕組みと対応フロー

USE CASES

03業務に活かせるユースケース

ユースケース① Customer Account UI拡張でアプリ独自データを表示

課題: マイページUI拡張にアプリ固有のメタフィールド（会員ランク・ポイント残高など）を表示していたが、今回の変更で突然値が空になった。
打ち手: metafieldDefinitionCreate ミューテーションで当該メタフィールドの定義を作成し、access.customerAccounts を有効化。アプリのTOMLに declarative_metafields として宣言することで、インストール時に自動で定義が作られる仕組みを構築する。
効果: UI拡張から再びメタフィールドの値が取得できるようになり、カスタマーアカウント体験が復旧・安定化する。
技術メモ: Customer Account UI拡張を使っているすべてのストアに対して定義作成が必要。既存インストール済みストア分は一括でAPIを叩く移行スクリプトを用意すること。

ユースケース② HydrogenのカスタムストアフロントでメタフィールドをAPIから取得

課題: HydrogenベースのHeadlessストアでサーバーサイドからCustomer Account APIを叩き、アプリメタフィールドをパーソナライズ表示に使っていたが、レスポンスに null が返るようになった。
打ち手: 対象メタフィールドすべてに定義を作成し、定義のアクセス設定でCustomer Account APIからの読み取りを許可する。TOMLの宣言的メタフィールド設定と合わせて管理フローを整備する。
効果: Hydrogenフロントエンドのパーソナライズ機能が正常稼働し、ストア固有の顧客体験を維持できる。
技術メモ: Headlessストアは複数店舗展開が多いため、新規インストールフック（アプリのインストールWebhook等）で metafieldDefinitionCreate を自動実行するよう実装を見直すこと。

ユースケース③ 複数ストア運用アプリの定義一括整備

課題: 数十〜数百店舗に導入済みのアプリで、全ストアのアプリメタフィールドに定義が存在しない状態が発覚した。手動対応は現実的でない。
打ち手: インストール済み全ストアのリストを取得し、各ストアに対して metafieldDefinitionCreate をAdmin APIで順次実行するバッチスクリプトを作成して移行を完了させる。あわせてTOMLに宣言的定義を追加し、今後のインストールは自動化する。
効果: 全インストール済みストアでCustomer Account APIからのメタフィールドアクセスが復旧し、将来の新規インストールでも自動的に定義が作成される状態になる。
技術メモ: Admin APIのレート制限（Throttling）に注意しながらバッチを実行すること。定義作成の冪等性を担保するため、既存定義の有無を事前確認してからミューテーションを呼ぶ設計が望ましい。

DEVELOPER NOTES

04技術者目線のポイント

項目	詳細
影響対象	アプリリソース所有のメタフィールドをCustomer Account APIで取得しているアプリ。Customer・Orderリソースのメタフィールドは影響なし。
必須アクション	アプリが利用する全メタフィールドに `metafieldDefinitionCreate` を実行し、定義を作成。Customer Account APIアクセス権限を定義に付与する。
宣言的メタフィールド	アプリ管理のメタフィールドはTOMLファイルに `declarative_metafields` として記述することで、インストール時に自動定義作成が可能になる。
既存インストール済みストアへの対応	TOMLの宣言的設定だけでは既存ストアは救われない。インストール済みの全ストアに対して個別に `metafieldDefinitionCreate` を実行する移行スクリプトが必要。
アクセス設定	定義を作成するだけでは不十分。定義のアクセス設定でCustomer Account APIからの読み取りを明示的に許可する必要がある。

📌 影響を受けないケース

Customer リソース所有のメタフィールド（今回の変更対象外）
Order リソース所有のメタフィールド（今回の変更対象外）
すでに定義とCustomer Account API権限が設定済みのアプリメタフィールド
Admin APIやStorefront API経由でのメタフィールドアクセス（本変更はCustomer Account API限定）

SUMMARY

05提案で使える一言サマリ

「Customer Account APIでアプリメタフィールドを利用するすべてのストアは、定義作成とアクセス権限設定の対応が2026年6月16日より必須となっています。マイページUI拡張・Hydrogen・Headlessストアへの影響を早急に確認し、未対応であればメタフィールド定義の一括整備を今すぐ実施することをお勧めします。」

Source: https://shopify.dev/changelog/metafields-now-require-a-definition-to-be-accessed-through-the-customer-account-api | 公開日: 2026年6月16日