As of Storefront API version 2027-01, the metafields field on the Market object matches each requested key in any case, as Market.metafield already does. This is a breaking change for apps and custom storefronts that request a market metafield key in a different case from the stored key, or that read a key that the buyer's markets store that differ by letter case. If your app does either, review its Market.metafields queries before you move it to 2027-01.
What changed
In version 2027-01, Market.metafields returns a metafield when the requested key matches the stored key in any case. In earlier versions, Market.metafields returns a metafield only when the requested key and the stored key have the same case.
For example, a market stores a metafield with the namespace custom and the key colour:
- In version
2026-10and earlier, the entry for{ namespace: "custom", key: "Colour" }isnull. - In version
2027-01, the entry returns the stored metafield.
Who's affected
The change applies to apps and custom storefronts that query metafields on a Market object, from Localization.market or Country.market, with Storefront API version 2027-01 or later. Your app is affected only if one of these conditions is true:
- It requests a key in a different case from the key that the market stores.
- The buyer's markets store the same key in different cases.
Your app isn't affected if it requests each key in the case that the markets store it, or if it uses only Market.metafield, which already matches keys in any case. Versions 2026-10 and earlier don't change.
Why this matters
In earlier versions, Market.metafield and Market.metafields can return different results for the same key: Market.metafield finds the metafield, and Market.metafields returns null. In 2027-01, both fields return the same metafield, so your storefront shows the same value whichever field it queries.
What to do
Market.metafield already matches keys case-insensitively, and it returns the metafield from the buyer's most specific market. So on the version that you use today, Market.metafield returns the result that Market.metafields returns in 2027-01. You can compare the two fields to find out whether the change affects your app.
- For each market metafield that your app reads, query
Market.metafieldandMarket.metafieldswith the same namespace and key, and compare the results. - If the results are the same for every key, then you don't need to make changes.
- If a result is different, then check whether the difference has a material impact on your app or your storefront.
- If it does, then update your app and your metafields so that they don't depend on the case of keys. For example, request each key in the case that your markets store it, and use one case for each key on every market.
query CompareMarketMetafields @inContext(country: CA) {
localization {
market {
metafield(namespace: "custom", key: "Colour") {
key
value
}
metafields(identifiers: [{ namespace: "custom", key: "Colour" }]) {
key
value
}
}
}
}