---
title: >-
  Market metafields break ties between equally specific markets by market handle
  - 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-break-ties-between-equally-specific-markets-by-market-handle
  md: >-
    https://shopify.dev/changelog/posts/market-metafields-break-ties-between-equally-specific-markets-by-market-handle.md
metadata:
  effectiveApiVersion: 2026-01
  affectedApi:
    - displayName: Functions
      handle: functions-api
    - displayName: Liquid
      handle: liquid
    - displayName: Metafields and metaobjects
      handle: metafields-metaobjects
    - displayName: Storefront API
      handle: storefront-graphql
  primaryTag:
    displayName: API
    handle: api
  secondaryTag:
    displayName: Update
    handle: update
  indicatesActionRequired: false
  createdAt: '2026-11-10T13:24:41-05:00'
  postedAt: '2026-11-13T12:00:00-05:00'
  updatedAt: '2026-11-10T14:09:39-05:00'
  effectiveAt: '2026-11-13T12:00:00-05:00'
---

November 13, 2026

# Market metafields break ties between equally specific markets by market handle

DateNovember 13, 2026

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

FlagsUpdate

Tags[Functions](https://shopify.dev/changelog?api_type=functions-api)[Liquid](https://shopify.dev/changelog?api_type=liquid)[Metafields and metaobjects](https://shopify.dev/changelog?api_type=metafields-metaobjects)[Storefront API](https://shopify.dev/changelog?api_type=storefront-graphql)

When a buyer matches two or more equally specific markets that set the same metafield, `Market.metafield` and `Market.metafields` now return the value from the market with the lowest handle, instead of the value that was updated most recently. This behavior change applies to the Storefront API, Liquid, and Function APIs on every API version. If your app or theme reads market metafields on stores with overlapping markets, check which value buyers get in a tie.

***

## What changed

A buyer can match more than one market. When several of those markets set the same metafield, the value comes from the most specific market. That doesn’t change.

When the most specific markets that set the metafield are equally specific, one of their values has to win. Before this change, the value that was updated most recently won. With this change, the value from the market with the lowest handle wins.

For example, a buyer in Canada matches two region markets: one for Canada and the United States, with the handle `canada-us`, and one for Canada and Mexico, with the handle `canada-mexico`. Neither market is more specific than the other, and both set the `custom.banner` metafield:

* Before this change, the buyer got the `custom.banner` value that was updated most recently.
* After this change, the buyer gets the value from `canada-mexico`, because `canada-mexico` comes before `canada-us`.

Handles are compared by byte value, one character at a time. For handles that use only lowercase letters, digits, and hyphens, this is alphabetical order, with hyphens before digits and digits before letters.

## Who’s affected

Shopify is rolling out this change first to stores where the new tie break behavior doesn’t change which values buyers see. For stores that might be affected, Shopify will contact merchants so they can adjust market handles before the change applies to their store.

The change applies to every API version of these fields:

* Storefront API: `Market.metafield` and `Market.metafields` (see <https://shopify.dev/docs/api/storefront/latest/objects/Market>)
* Liquid: `localization.market.metafields` (see <https://shopify.dev/docs/api/liquid/objects/market>)
* Function APIs: `Market.metafield` in each Function API whose input includes a market (for example, <https://shopify.dev/docs/api/functions/latest/delivery-customization#Input.fields.localization.market.metafield>)

These APIs returns different value only when all of these conditions are true:

* The buyer matches two or more equally specific markets that set the same metafield.
* No more specific market that the buyer matches sets that metafield.
* The tied markets store different values, and the most recently updated value isn’t the value from the market with the lowest handle.

## Why this matters

The update time of a metafield isn’t visible in the Shopify admin. Merchants couldn’t see or control which value buyers got, and editing a metafield on one market could change what buyers in an overlapping market saw. Market handles are visible and editable in the Shopify admin, so merchants can choose which market wins a tie.

## What to do

No action is needed for app partners.