Skip to main content

Markets inheritance

Note

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.


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:

Market inheritance
  • 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

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.

Market AMarket BInferred relationship
Region is CanadaCompany location is in CanadaMarket A is a parent of Market B
All company locationsCompany location is in FranceMarket A is a parent of Market B
Region is CanadaPOS location A is in CanadaMarket A is a parent of Market B
Regions are Canada and USRegion is CanadaMarket A is a parent of Market B
Region is CanadaRegion is USNo parentage inferred
Regions are Canada and USRegions are Canada and MexicoNo parentage inferred
Company locations are A, B, and CCompany locations are A and BNo parentage inferred

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.

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.

Canadian market inheritance example


Was this page helpful?