Skip to main content

Migrate to market metafields

If your app uses a market's ID or handle to decide which experience to show a buyer, then it relies on deprecated single-market endpoints. In this guide, you'll learn why those endpoints are deprecated, which field replaces each one, and how to move live app configurations to market metafields without breaking them.


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 return only country-based markets:

These endpoints are deprecated as of API version 2025-04.


Anchor to Why single-market endpoints are deprecatedWhy single-market endpoints are deprecated

Before market inheritance, a buyer belonged to exactly one market. Apps could use market.id or market.handle to decide which experience to show. For example, "If the market is North America, then show this banner."

Now, merchants can create child markets, such as a Canada market under a North America market. A buyer in Canada matches both markets. The deprecated single-market endpoints return only the most specific market, Canada, and not the parent market, North America.

If an app targets the North America market by its ID, then buyers in Canada stop matching, because the API now returns the ID of the Canada market. This happens each time a merchant creates a child market, so the merchant has to configure the app again each time.

A buyer can also match two overlapping markets at the same level, such as a Canada and United States market and a Canada and Mexico market. The deprecated single-market endpoints return only one of these markets, so an app that targets the other market doesn't match buyers in Canada.

Market IDs and handles aren't stable identifiers for targeting buyers.


Anchor to How market metafields replace market IDsHow market metafields replace market IDs

Instead of using a market's ID or handle to decide which experience to show a buyer, associate your app's custom data directly with markets as market metafields. Markets define conditions, such as a geographical region, a location, or a company location, that describe which buyers they apply to. When a buyer meets those conditions, Shopify resolves the market metafield values that apply to the buyer from the buyer's matching markets. A more specific market automatically falls back to the metafield values of a less specific market.

Your app then uses the resolved values to show the buyer a custom experience. Unlike the deprecated single-market endpoints, which resolve only country markets, market metafields also resolve for other market types, such as B2B markets.

Learn how market metafields resolve.



Anchor to Replace each deprecated endpointReplace each deprecated endpoint

The following table lists each deprecated single-market endpoint, the field that replaces it, and the API versions that include the replacement:

APIDeprecated fieldReplacementAPI version
Liquidlocalization.market.id, localization.market.handle, country.market.id, and country.market.handlelocalization.market.metafieldsNot versioned
Storefront APILocalization.market and Country.marketLocalization.marketsMetafield and Localization.marketsMetafields. Learn how to query them.unstable, planned for 2027-01
Function APIslocalization.market and the market field of an address, such as deliveryAddress.marketlocalization.marketsMetafield, for example in the Discount Function API. Learn how to read it in a function.unstable, planned for 2027-01
Checkout UI extensionsshopify.localization.market and useLocalizationMarketNo replacement yet. Until a replacement is available, keep using these fields. You can set market metafields now, so that they're ready when the replacement is available.Planned for 2027-01
Customer Account APICompanyLocation.marketTo target specific company locations, use CompanyLocation.metafield.

To find the market metafield values that apply to the logged-in customer, query the Storefront API.
All supported versions
GraphQL Admin APICustomer.marketTo target specific customers, use Customer.metafield.

To find the market metafield values that apply to the country of a customer's default address, query the Storefront API.
All supported versions
GraphQL Admin APICompanyLocation.marketTo target specific company locations, use CompanyLocation.metafield.

To find the market metafield values that apply to the country of a company location's shipping address, query the Storefront API.
All supported versions
GraphQL Admin APIMarketWebPresence.marketMarketWebPresence.marketsAll supported versions
Note

The Storefront API doesn't immediately reflect the changes that a merchant makes to their store's configuration. Use the Storefront API to find what applies to a buyer, not to manage the store's current configuration in the Shopify admin.


The following tips help you migrate live configurations to market metafields.

Anchor to Use the parallel change pattern for live configurationsUse the parallel change pattern for live configurations

If your app already targets buyers with a deprecated market ID or handle, then consider migrating in phases. A phased migration lowers the risk of breaking live configurations, and makes the new logic easier to test and to switch back:

  1. Add logic that targets markets with market metafields: Keep the legacy logic, and add a flag to each configuration that chooses which logic it uses, such as "use_market_metafield": true. From then on, when your app saves a configuration that targets markets, it also writes the configuration's market metafields. Turn on the flag for new configurations.
  2. Deprecate the legacy logic: Stop merchants from adding market targeting to legacy configurations. Existing legacy configurations keep working with no change.
  3. Find the affected shops: These are the shops with legacy configurations that target markets by ID or handle, and that don't have market metafields yet.
  4. Migrate those configurations: Set the market metafields for each configuration that doesn't have them, and then turn on the flag to switch the configuration to the new logic.
  5. Remove the legacy market targeting logic: Remove it after every affected shop is migrated.

The flag lets you set market metafields without changing how a configuration behaves, because nothing changes until you turn on the flag. It also makes it easy to revert: turn off the flag to return a configuration to the legacy logic.

Anchor to Verify behavioral parity in functionsVerify behavioral parity in functions

Functions are deterministic: for the same input, they always return the same output. You can use this to check that a configuration behaves the same before and after you turn on its flag. Copy the input of a recorded run from the run details in the Dev Dashboard, turn on the flag in the input's configuration, run the function locally with Shopify CLI, and compare the output with the recorded output.

The comparison is valid only if the input includes the market metafield values that the new logic reads. Because the migration sets the market metafields before it turns on the flag, recorded runs can include the real values.



Was this page helpful?