Markets inheritance
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 Resolving marketsResolving markets
A market can have one or more parent markets. If a market does not define a customization, it will inherit the customization from its parents, or the store defaults if no customization is defined on any parent.
Let's imagine you have an online store that sells products to customers in Canada and the United States. You want to offer the same products for each country, with specific pricing for each country. You also want to sell your products directly to businesses all over the United States, and have a few retail locations in Canada.
Your market structure might look like this:

-
A buyer from the USA would match the Canada + USA market as well as the USA market.
-
A buyer from Canada would match the Canada + USA market as well as the Canada market.
-
A B2B buyer from the United States would match the All B2B in USA market.
-
A buyer from the Montreal physical store would match the Montreal POS Location market.
Anchor to Market Precedence StackMarket Precedence Stack
When a buyer is a member of multiple markets, the Market system will rank them in order of most specific.
The most-specific ranking is as follows:
- Company Location
- Retail Location
- Region
- Store Default
Anchor to LineageLineage
Markets have a parent-child relationship with, at minimum, the Store Default as a universal parent. A parent-child relationship is inferred between two markets when the region on the child market is a strict subset of the condition on the parent market, or if the address of the POS location or company location on the child market is within the region of the parent market.
We do not consider specific-location rules such as "Specific retail locations" and "Specific company locations" to determine the lineage of a market. For example, we don't consider a Market with company locations B and C to be a child of a Market with A, B, and C.
Anchor to ExamplesExamples
Market A | Market B | Inferred relationship |
---|---|---|
Region is Canada | Company location is in Canada | Market A is a parent of Market B |
All company locations | Company location is in France | Market A is a parent of Market B |
Region is Canada | POS location A is in Canada | Market A is a parent of Market B |
Regions are Canada and US | Region is Canada | Market A is a parent of Market B |
Region is Canada | Region is US | No parentage inferred |
Regions are Canada and US | Regions are Canada and Mexico | No parentage inferred |
Company locations are A, B, and C | Company locations are A and B | No parentage inferred |
Anchor to InheritanceInheritance
Inheritance allows you to group some customizations under a parent market, and then apply the same customization to a child market.
For example, if a Market has no customization for currency, then we go up the lineage to find the first instance of a customization. This may take us up all the way to the store default. In the case where a market has more than one parent, we prioritize the most-specific parent.
Some inherited customizations are overridden when redefined on the child market, and some are added to the child market.
Inherited Catalogs and WebPresences are added to the child market. CurrencySettings and PriceInclusions are overridden.
Anchor to ExamplesExamples
In the following example, a buyer from Canada will match the Canada market.
The Canada market will evaluate the "Canada" and "CA + USA" catalogs to retrieve the products and pricing. It inherits the currency from the parent market (local currency) and inherits the web presence from the store default.

Anchor to Next stepsNext steps
- Learn how to use the
marketCreate
mutation.