Skip to main content

Work with subdivision markets

A subdivision market is a market whose region condition targets a country subdivision, such as a state, province, or prefecture, instead of a whole country. Subdivision markets extend region markets: a region market can contain whole countries, individual subdivisions, or a mix of both.

This guide explains the API contract for subdivision markets: how to read a market's subdivision membership, and how to create or update markets with subdivision conditions.

Anchor to How subdivision markets are modeledHow subdivision markets are modeled

A market's region membership is a flat list of concrete region nodes. A subdivision market doesn't model a nested tree of subdivisions, and you don't need to traverse a hierarchy to determine membership. Each node in the list is one of the following concrete types, all of which implement the MarketRegion interface:

Region typeRepresentsKey fields
MarketRegionCountryA whole country.code (country code)
MarketRegionSubdivisionA country subdivision, such as a state, province, or prefecture.code (subdivision code), country { code }

Read and write subdivision membership using MarketRegionSubdivision and its subdivision input.

Anchor to Read membership from ,[object Object]Read membership from conditions.regionsCondition.regions

The source of truth for a market's region membership, including its subdivisions, is the regions connection on the market's conditions.regionsCondition.

Caution

Don't use the top-level Market.regions field as the source of truth for subdivision membership. It's deprecated. Read membership from conditions.regionsCondition.regions instead.

Anchor to Read a subdivision market's membershipRead a subdivision market's membership

To read which subdivisions a market targets, query conditions.regionsCondition.regions and use an inline fragment on MarketRegionSubdivision to select the subdivision code and its country.

POST https://{shop}.myshopify.com/admin/api/{api_version}/graphql.json

Read a market's region membership

query MarketRegionMembership($id: ID!) {
market(id: $id) {
id
name
conditions {
conditionTypes
regionsCondition {
applicationLevel
regions(first: 50) {
nodes {
id
name
__typename
... on MarketRegionCountry {
code
}
... on MarketRegionSubdivision {
code
country {
code
}
}
}
}
}
}
}
}

JSON response

{
"data": {
"market": {
"id": "gid://shopify/Market/1",
"name": "California",
"conditions": {
"conditionTypes": ["REGION"],
"regionsCondition": {
"applicationLevel": "SPECIFIED",
"regions": {
"nodes": [
{
"id": "gid://shopify/MarketRegionSubdivision/2",
"name": "California",
"__typename": "MarketRegionSubdivision",
"code": "CA",
"country": {
"code": "US"
}
}
]
}
}
}
}
}
}

Iterate over the regions nodes and branch on __typename to handle whole-country (MarketRegionCountry) and subdivision (MarketRegionSubdivision) nodes. Because membership is a flat list, you don't need to expand or resolve any nested structure.

Anchor to Identify subdivision marketsIdentify subdivision markets

Note

The Admin API doesn't expose a dedicated subdivision-market filter. Apps can identify subdivision markets by reading conditions.regionsCondition.regions and checking for MarketRegionSubdivision nodes.

There's no first-class way to ask the API for only subdivision markets. Instead, list region markets (filter the markets query by type: REGION) and identify subdivision markets client-side: a market is a subdivision market if any node in its conditions.regionsCondition.regions is a MarketRegionSubdivision.

POST https://{shop}.myshopify.com/admin/api/{api_version}/graphql.json

List markets with their region membership

query Markets {
markets(first: 50, type: REGION) {
nodes {
id
name
conditions {
conditionTypes
regionsCondition {
regions(first: 50) {
nodes {
__typename
... on MarketRegionCountry {
code
}
... on MarketRegionSubdivision {
code
country {
code
}
}
}
}
}
}
}
}
}

Then treat a market as a subdivision market when any of its region nodes is a MarketRegionSubdivision:

const isSubdivisionMarket = market.conditions?.regionsCondition?.regions?.nodes?.some(
(region) => region.__typename === "MarketRegionSubdivision",
) ?? false;

Anchor to Create a subdivision marketCreate a subdivision market

To create a subdivision market, pass the subdivision in the regionsCondition.regions input. Each region input takes a countryCode and an optional subdivision code.

POST https://{shop}.myshopify.com/admin/api/{api_version}/graphql.json

Create a market for California

mutation CreateCaliforniaMarket {
marketCreate(input: {
name: "California",
status: ACTIVE,
conditions: {
regionsCondition: {
regions: [
{
countryCode: US,
subdivision: "CA"
}
]
}
}
}) {
market {
id
name
conditions {
conditionTypes
regionsCondition {
applicationLevel
regions(first: 10) {
nodes {
id
name
__typename
... on MarketRegionSubdivision {
code
country { code }
}
}
}
}
}
}
userErrors { field code message }
}
}

JSON response

{
"data": {
"marketCreate": {
"market": {
"id": "gid://shopify/Market/1",
"name": "California",
"conditions": {
"conditionTypes": ["REGION"],
"regionsCondition": {
"applicationLevel": "SPECIFIED",
"regions": {
"nodes": [
{
"id": "gid://shopify/MarketRegionSubdivision/2",
"name": "California",
"__typename": "MarketRegionSubdivision",
"code": "CA",
"country": { "code": "US" }
}
]
}
}
}
},
"userErrors": []
}
}
}

You can mix whole-country and subdivision conditions in the same market. Omit subdivision to target the whole country, or include it to target a single subdivision within that country.

Anchor to Update a subdivision marketUpdate a subdivision market

To change which regions a market targets, use marketUpdate. Unlike marketCreate, the conditions argument on marketUpdate is a delta: add regions with conditionsToAdd and remove regions with conditionsToDelete, each of which takes the same regionsCondition shape. The example below adds two U.S. states to a market.

POST https://{shop}.myshopify.com/admin/api/{api_version}/graphql.json

Add California and New York to a market

mutation AddSubdivisionsToMarket($id: ID!) {
marketUpdate(id: $id, input: {
conditions: {
conditionsToAdd: {
regionsCondition: {
regions: [
{ countryCode: US, subdivision: "CA" },
{ countryCode: US, subdivision: "NY" }
]
}
}
}
}) {
market {
id
name
conditions {
regionsCondition {
regions(first: 10) {
nodes {
id
name
__typename
... on MarketRegionSubdivision {
code
country { code }
}
}
}
}
}
}
userErrors { field code message }
}
}

Anchor to Responder supportResponder support

Not every part of Shopify that reads market configuration ("responders") supports subdivision markets yet. Delivery and shipping is the first supported responder. The market-driven shipping feature preview owns rollout dates, the ShopFeatures.marketDrivenShipping feature, Market.delivery, and app-owned delivery-profile guidance.

Note

Don't assume that other areas, such as discounts, catalogs, theme contextualization, Market Manager, or market metafields, support subdivision markets. Support is added per responder. Confirm a responder's support before relying on subdivision-level behavior there.

Treat market membership as configuration data, not as a behavior contract. Don't infer a market's effective shipping or tax behavior from its raw region membership. Read effective behavior from the responder's own API surface (for example, the Delivery APIs for shipping) rather than reconstructing it from the regions a market targets.

Anchor to Next stepsNext steps

Was this page helpful?