On this page
Why this happens or what changed
A buyer can match multiple markets, including two overlapping regional markets. Shopify still prefers a more specific market. Only when equally specific matching markets set the same namespace/key does the new deterministic tie-break matter. The change affects localization.market.metafields in Liquid, Storefront API Market.metafield(s), and relevant Function inputs across API versions. Shopify is staging the rollout and contacting merchants whose values could change.
Practical fix
- List the overlapping markets for each affected country and identify their visible handles in Shopify admin.
- For the same namespace and key, record each market’s stored value and determine whether a more specific market overrides the overlap.
- Where the equally specific markets conflict, compare handles byte-by-byte. For ordinary lowercase handles, the earlier alphabetical handle wins; hyphens sort before digits and letters.
- Prefer eliminating unnecessary conflicting values or making market definitions more specific. Do not repeatedly edit a metafield to try to change priority.
- Verify the actual buyer country and language context in storefront and Function behavior; document intentional precedence before changing handles.
Production example
Suppose canada-us and canada-mexico both include Canada and both define custom.banner. When equally specific, canada-mexico wins because its handle sorts first. A newer edit to canada-us no longer overrides it. This is a market selection issue, not a missing translation.
{% assign market_banner = localization.market.metafields.custom.banner %}
{% if market_banner != blank %}{{ market_banner.value | escape }}{% endif %}
How to test this
- Use a test market overlap where two equally specific markets set distinct banner values.
- Visit from the affected buyer country and record the Liquid-rendered banner.
- Query the matching market metafield via Storefront API and compare its value to the theme.
- Verify that a more specific market still takes precedence when it sets the same key.
- Edit the non-winning value in a controlled test and confirm it no longer changes the selected value; restore test data.

