---
title: Migrate to market metafields
description: >-
  Learn how to migrate your app from deprecated single-market endpoints to
  market metafields, so your app keeps targeting the right buyers when merchants
  create, nest, or reorganize markets.
source_url:
  html: 'https://shopify.dev/docs/apps/build/markets/migrate-to-market-metafields'
  md: 'https://shopify.dev/docs/apps/build/markets/migrate-to-market-metafields.md'
---

# 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](https://shopify.dev/docs/apps/build/markets/market-metafields) without breaking them.

***

## Deprecated 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:

* **Liquid**: [`localization.market`](https://shopify.dev/docs/api/liquid/objects/localization#localization-market), [`country.market`](https://shopify.dev/docs/api/liquid/objects/country#country-market).
* **Storefront API**: [`Localization.market`](https://shopify.dev/docs/api/storefront/latest/objects/Localization#field-Localization.fields.market), [`Country.market`](https://shopify.dev/docs/api/storefront/latest/objects/Country#field-Country.fields.market).
* **Shopify Functions input**: [`localization { market }`](https://shopify.dev/docs/api/functions/latest/delivery-customization#Input.fields.localization.market), [`deliveryAddress { market }`](https://shopify.dev/docs/api/functions/latest/delivery-customization#Input.fields.cart.deliveryGroups.deliveryAddress.market).
* **Checkout UI extensions**: [`shopify.localization.market`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/target-apis/platform-apis/localization-api#docsstandardlocalizationapi-propertydetail-localization), [`useLocalizationMarket`](https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/target-apis/platform-apis/localization-api#useLocalizationMarket).
* **GraphQL Admin API**: [`Customer.market`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Customer#field-Customer.fields.market), [`CompanyLocation.market`](https://shopify.dev/docs/api/admin-graphql/latest/objects/CompanyLocation#field-CompanyLocation.fields.market), [`MarketWebPresence.market`](https://shopify.dev/docs/api/admin-graphql/latest/objects/MarketWebPresence#field-MarketWebPresence.fields.market).
* **Customer Account API**: [`CompanyLocation.market`](https://shopify.dev/docs/api/customer/latest/objects/CompanyLocation#field-CompanyLocation.fields.market).

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

***

## Why single-market endpoints are deprecated

Before [market inheritance](https://shopify.dev/docs/apps/build/markets/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.

***

## How 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](https://shopify.dev/docs/apps/build/markets/market-metafields#how-market-metafields-resolve).

***

## Requirements

* Your app uses one or more of the [deprecated single-market endpoints](#deprecated-single-market-endpoints).
* You're familiar with [using market metafields](https://shopify.dev/docs/apps/build/markets/market-metafields).

***

## Replace 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:

| API | Deprecated field | Replacement | API version |
| - | - | - | - |
| Liquid | `localization.market.id`, `localization.market.handle`, `country.market.id`, and `country.market.handle` | [`localization.market.metafields`](https://shopify.dev/docs/apps/build/markets/market-metafields#liquid) | Not versioned |
| Storefront API | `Localization.market` and `Country.market` | [`Localization.marketsMetafield`](https://shopify.dev/docs/api/storefront/unstable/objects/Localization#field-Localization.fields.marketsMetafield) and [`Localization.marketsMetafields`](https://shopify.dev/docs/api/storefront/unstable/objects/Localization#field-Localization.fields.marketsMetafields). Learn how to [query them](https://shopify.dev/docs/apps/build/markets/market-metafields#storefront-api). | `unstable`, planned for `2027-01` |
| Function APIs | `localization.market` and the `market` field of an address, such as `deliveryAddress.market` | `localization.marketsMetafield`, for example in the [Discount Function API](https://shopify.dev/docs/api/functions/unstable/discount#Input.fields.localization.marketsMetafield). Learn how to [read it in a function](https://shopify.dev/docs/apps/build/markets/market-metafields#shopify-functions). | `unstable`, planned for `2027-01` |
| Checkout UI extensions | `shopify.localization.market` and `useLocalizationMarket` | No 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 API | `CompanyLocation.market` | To target specific company locations, use [`CompanyLocation.metafield`](https://shopify.dev/docs/api/customer/latest/objects/CompanyLocation#field-CompanyLocation.fields.metafield). To find the market metafield values that apply to the logged-in customer, query the [Storefront API](https://shopify.dev/docs/apps/build/markets/market-metafields#storefront-api). | All supported versions |
| GraphQL Admin API | `Customer.market` | To target specific customers, use [`Customer.metafield`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Customer#field-Customer.fields.metafield). To find the market metafield values that apply to the country of a customer's default address, query the [Storefront API](https://shopify.dev/docs/apps/build/markets/market-metafields#storefront-api). | All supported versions |
| GraphQL Admin API | `CompanyLocation.market` | To target specific company locations, use [`CompanyLocation.metafield`](https://shopify.dev/docs/api/admin-graphql/latest/objects/CompanyLocation#field-CompanyLocation.fields.metafield). To find the market metafield values that apply to the country of a company location's shipping address, query the [Storefront API](https://shopify.dev/docs/apps/build/markets/market-metafields#storefront-api). | All supported versions |
| GraphQL Admin API | `MarketWebPresence.market` | [`MarketWebPresence.markets`](https://shopify.dev/docs/api/admin-graphql/latest/objects/MarketWebPresence#field-MarketWebPresence.fields.markets) | All 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.

***

## Migration tips

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

### Use 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.

### Verify 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](https://shopify.dev/docs/apps/build/functions/monitoring-and-errors#access-function-run-details), turn on the flag in the input's configuration, [run the function locally with Shopify CLI](https://shopify.dev/docs/apps/build/functions/test-debug-functions#execute-the-function-locally-using-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.

***

## Next steps

* Learn how to [use market metafields](https://shopify.dev/docs/apps/build/markets/market-metafields).

***
