STOREFRONT API

Storefront API 2027-01:
Market.metafieldsがケース非依存マッチングに対応

大文字・小文字の違いで null を返していた挙動が修正。破壊的変更として移行前の確認が必須です。

2026-10 以前key: "Colour" でクエリ保存キー: "colour"metafields → null2027-01 以降key: "Colour" でクエリ保存キー: "colour"metafields → 値を返す ✓

Storefront API 2027-01 より、Market.metafields はリクエストしたキーと保存キーの大文字・小文字が異なっても一致するよう変更されます。影響を受けるのはキーのケースが保存値と異なる形でクエリしているアプリ・カスタムストアフロントです。2027-01 へ移行する前に既存クエリの動作確認が必要です。

1変更内容の詳細:Before / After 図解

Market.metafields キーマッチング比較▼ 2026-10 以前(厳密ケース一致)保存: namespace="custom", key="colour"クエリ: key="Colour" (大文字C)Market.metafield → 値を返すMarket.metafields → null⚠ 同じキーで異なる結果が生じる▼ 2027-01 以降(ケース非依存)保存: namespace="custom", key="colour"クエリ: key="Colour" (大文字C)Market.metafield → 値を返すMarket.metafields → 値を返す✓ 両フィールドが同じ結果を返す

2影響を受けるケース/受けないケース

条件 影響
保存キーと異なるケースでキーをリクエストしている 影響あり
複数マーケットで同じキーを異なるケースで保存している 影響あり
保存キーと同じケースで常にリクエストしている 影響なし
Market.metafield(単数形)のみ使用している 影響なし
Storefront API 2026-10 以前のバージョンを使用し続ける 影響なし

3業務に活かせる具体ユースケース

課題
国際対応ストアで市場ごとの送料ルールをメタフィールドで管理しており、フロント側のクエリが key: "ShippingRule"、管理画面での保存が key: "shippingrule" と一致していない。現行では metafields が null を返し、送料が正しく表示されない。
打ち手
2027-01 移行後は大文字・小文字を気にせず値が返るため、フロント側のクエリを修正せずとも正しい送料を取得できる。ただし移行前に CompareMarketMetafields クエリで差分を確認し、意図しない値の変化がないか検証する。
効果
送料表示の不整合が解消され、カート離脱率の改善が期待できる。複数地域展開時のメタフィールド管理コストも削減。
技術メモ
Localization.market 経由で metafields をクエリする実装が対象。バージョン指定が 2027-01 以降であることを確認すること。
課題
複数マーケットを管理する際、マーケットAでは key: "promoText"、マーケットBでは key: "PromoText" と誤って異なるケースで登録されている。バイヤーのマーケットによってプロモーション文言が表示されたりされなかったりする。
打ち手
2027-01 以降は同じキーの異なるケース表記が一致扱いになるため、表示が安定する。ただし元記事に「buyer's markets store the same key in different cases」がある場合は影響ありと明記されているため、ケースを統一する対応を推奨。
効果
プロモーション表示の一貫性が確保され、マーケット担当者のオペレーションミスによる機会損失を防止できる。
技術メモ
長期的には全マーケットでキーのケースを統一する運用ルールを設けることを推奨。ケースの混在は将来の予期しないマッチングを引き起こす可能性がある。
課題
ヘッドレスコマース構成でReact製カスタムストアフロントがあり、Market.metafield(単数)と Market.metafields(複数)を混在使用。開発時にテストしたところ両者の結果が異なり、どちらの値を使うべきか判断できない。
打ち手
2027-01 移行後は両フィールドが同じ結果を返すため、コンポーネントごとに使用するフィールドを統一できる。移行前に元記事掲載の CompareMarketMetafields クエリを実行し、結果の差分がないことを確認してから移行する。
効果
フロントエンド実装の一貫性が高まり、コードの可読性・保守性が向上。QAコストも削減できる。
技術メモ
クエリ例: query CompareMarketMetafields @inContext(country: CA) で metafield と metafields の両方を同一 namespace / key で取得し結果を比較する。差分がなければ移行しても安全。

4技術者向けチェックポイント

🔖 対象APIバージョン

Storefront API 2027-01 以降が対象。2026-10 以前は挙動変更なし。

⚠ 破壊的変更の分類

公式が breaking change と明記。影響有無に関わらず 移行前に必ず確認が必要。

🔍 影響調査クエリ

Market.metafield と Market.metafields を同じ namespace / key で並列クエリし、返り値を比較する。差分がなければ移行しても安全。

📌 影響範囲の特定

Localization.market または Country.market 経由で metafields(複数形)をクエリしているコードを全てレビューすること。

✅ 推奨対応アクション

①全マーケットでキーのケースを統一する ②フロント側クエリのキーを保存値と同じケースに合わせる ③CompareMarketMetafields クエリで差分を検証する

📄 関連ドキュメント(元記事より)

Market object in the Storefront API / Storefront API 2027-01 reference / Retrieve metafields with the Storefront API / About Shopify API versioning

Storefront API 2027-01 への移行前に CompareMarketMetafields クエリで差分を確認し、メタフィールドキーのケース表記を全マーケットで統一することで、マーケット別コンテンツ配信の一貫性と安定性を確保できます。

Source: https://shopify.dev/changelog/market-metafields-matches-keys-in-any-case-as-of-storefront-api-version-2027-01 | 公開日: 2026年11月13日