Target buyers by country instead of market ID
We've received partner feedback raising concerns with the migration approach described in this guide. Please hold off on migrating using these steps. We're working on a revised solution and will follow up with updated guidance shortly.
We've received partner feedback raising concerns with the migration approach described in this guide. Please hold off on migrating using these steps. We're working on a revised solution and will follow up with updated guidance shortly.
If your app uses any of the deprecated single-market endpoints listed below, this guide explains why they're deprecated and what can go wrong.
Anchor to Deprecated single-market endpointsDeprecated single-market endpoints
The deprecated single-market endpoints are market objects with single market identifiers such as id, name, handle, and regions. These endpoints only surface country-based markets:
- Liquid:
Localization.market,Country.market. - Storefront API:
Localization.market,Country.market. - Shopify Functions input:
Localization { market },deliveryAddress { market }. - Checkout UI extensions:
shopify.localization.market,useLocalizationMarket. - GraphQL Admin API:
Customer.market,CompanyLocation.market,MarketWebPresence.market.
Anchor to Why single-market endpoints are deprecatedWhy single-market endpoints are deprecated
Before market inheritance was introduced, a buyer belonged to exactly one market, so apps could safely use market.id or market.handle to decide what experience to show (for example, "if the market is North America, show this banner").
Now, merchants can create child markets (for example, a Canada market under North America). A Canadian buyer matches both markets. The deprecated single-market endpoints only return the most specific one (Canada), not the parent (North America).
If an app was configured to target the "North America" market by ID, Canadian buyers stop matching because the API now returns "Canada" instead. And it happens every time a merchant creates a new child market, forcing merchants to reconfigure the app each time.
TL;DR: Market IDs are no longer stable identifiers for targeting buyers.