Market metafields break ties between equally specific markets by market handle

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.