About Shopify Markets developer preview
We're expanding Markets capabilities beyond region-based markets. New location-based (retail) and company location based (B2B) markets are now available, as well as enabling more customization options.
Not all merchant stores are eligible for the new markets experience. As an app developer, you must check if the shop is onboarded on the new markets experience before you can use the new marketCreate and marketUpdate mutations.
Anchor to How it worksHow it works
The following diagram describes the relationships between API objects related to markets:
| Api object | Description |
|---|---|
| Market | A group of one or more regions, company locations or retail locations to target sales. By creating a market, you can configure distinct, localized shopping experiences for customers. For example, you can configure currency, domains and languages, prices, published products, and theme customizations. |
| Condition | An attribute that qualifies a buyer for a market. For example, the region a buyer is located in, the company location they are purchasing on behalf of, or the retail location. |
Anchor to Market conditionsMarket conditions
Market conditions define what types of buyers are going to match certain markets.
-
A market with a
Regioncondition of Canada will match all buyers from that region. -
A market with a
CompanyLocationcondition of a certain company will match all logged buyers from that company location. -
A market with a
Locationcondition will match all POS buyers for that location.A market can also hold several conditions of the same type. For example, a market can hold several regions, like the US, Canada, or several company locations.
Markets also support wildcards, which contain all retail locations or all company locations for a geography. For example, you might want to include all company locations in all regions, or all POS locations in Canada.
Anchor to Market customizationsMarket customizations
A market can hold any combination of customizations.
CurrencySettings: Associate a particular currency with a given market.Catalogs: Associate one or more catalogs with the market.WebPresences: Associate one or more web presences with the market.PriceInclusions: Associate different pricing behaviour for taxes and duties with a particular market
Anchor to Notable API changesNotable API changes
The new markets are supported on the 2025-04 and above API versions. These APIs include changes and deprecations that the developers must be aware of. The list below highlights the most important changes:
| Field | Description | without new markets | 2025-04 & unstable with new markets |
|---|---|---|---|
QueryRoot.markets | Return the list of region markets on a store | Returns only region markets | Returns markets of all types (Region, B2B, Retail). |
Market.regions | Returns the list of regions associated with a market | A region can only be in a single market. | A region can appear in multiple markets |
The Market.catalogs | Returns the list of catalogs on a market | Markets always have 1 catalog | Market catalogs targeting regions, company locations and locations will be returned. 0 or many catalogs can be returned |
Market.currencySettings | The currency setting of a market | Non-nullable field | Nullable field |
Market.webPresences | The web presence of a market | Non-nullable field | Nullable field |
Market.webPresence | The web presence of a market (deprecated in favour of Market.webPresences) | Nullable field | Nullable field |
Anchor to Next stepsNext steps
- Learn how to check merchant eligibility to the new markets