---
title: >-
  Market.metafields matches keys in any case as of Storefront API version
  2027-01 - Shopify developer changelog
description: >-
  Shopify’s developer changelog documents all changes to Shopify’s platform.
  Find the latest news and learn about new platform opportunities.
source_url:
  html: >-
    https://shopify.dev/changelog/posts/market-metafields-matches-keys-in-any-case-as-of-storefront-api-version-2027-01
  md: >-
    https://shopify.dev/changelog/posts/market-metafields-matches-keys-in-any-case-as-of-storefront-api-version-2027-01.md
metadata:
  effectiveApiVersion: 2027-01
  affectedApi:
    - displayName: Storefront API
      handle: storefront-graphql
  primaryTag:
    displayName: API
    handle: api
  secondaryTag:
    displayName: Breaking API Change
    handle: breaking-api-change
  indicatesActionRequired: true
  createdAt: '2026-11-06T09:56:44-05:00'
  postedAt: '2026-11-13T12:00:00-05:00'
  updatedAt: '2026-11-10T14:02:07-05:00'
  effectiveAt: '2026-11-07T12:00:00-05:00'
---

November 13, 2026

# Market.metafields matches keys in any case as of Storefront API version 2027-01

DateNovember 13, 2026

Version[2027-01](https://shopify.dev/changelog?api_version=2027-01)

Flags[Breaking API Change](https://shopify.dev/changelog?filter=breaking-api-change)[Action required](https://shopify.dev/changelog?action_required=true)

Tags[Storefront API](https://shopify.dev/changelog?api_type=storefront-graphql)

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`](https://shopify.dev/docs/api/storefront/latest/objects/Market) 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-10` and earlier, the entry for `{ namespace: "custom", key: "Colour" }` is `null`.
* 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.

1. For each market metafield that your app reads, query `Market.metafield` and `Market.metafields` with the same namespace and key, and compare the results.
2. If the results are the same for every key, then you don't need to make changes.
3. If a result is different, then check whether the difference has a material impact on your app or your storefront.
4. 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.

```graphql
query CompareMarketMetafields @inContext(country: CA) {
  localization {
    market {
      metafield(namespace: "custom", key: "Colour") {
        key
        value
      }
      metafields(identifiers: [{ namespace: "custom", key: "Colour" }]) {
        key
        value
      }
    }
  }
}
```

## Related docs

* [`Market` object in the Storefront API](https://shopify.dev/docs/api/storefront/latest/objects/Market)
* [Storefront API 2027-01 reference](https://shopify.dev/docs/api/storefront/2027-01)
* [Retrieve metafields with the Storefront API](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/products-collections/metafields)
* [About Shopify API versioning](https://shopify.dev/docs/api/usage/versioning)