---
title: Work with subdivision markets
description: >-
  A subdivision market targets a country subdivision, such as a state, province,
  or prefecture. Learn how to read a market's subdivision membership and create
  or update subdivision markets with the GraphQL Admin API.
source_url:
  html: 'https://shopify.dev/docs/apps/build/markets/subdivision-markets'
  md: 'https://shopify.dev/docs/apps/build/markets/subdivision-markets.md'
---

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

***

## How 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`](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/MarketRegion) interface:

| Region type | Represents | Key fields |
| - | - | - |
| [`MarketRegionCountry`](https://shopify.dev/docs/api/admin-graphql/latest/objects/MarketRegionCountry) | A whole country. | `code` (country code) |
| `MarketRegionSubdivision` | A 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.

### Read membership from `conditions.regionsCondition.regions`

The source of truth for a market's region membership, including its subdivisions, is the [`regions`](https://shopify.dev/docs/api/admin-graphql/latest/objects/RegionsCondition) connection on the market's `conditions.regionsCondition`.

**Caution:**

Don't use the top-level [`Market.regions`](https://shopify.dev/docs/api/admin-graphql/latest/objects/Market) field as the source of truth for subdivision membership. It's deprecated. Read membership from `conditions.regionsCondition.regions` instead.

***

## Read a subdivision market's membership

To read which subdivisions a market targets, query `conditions.regionsCondition.regions` and use an [inline fragment](https://shopify.dev/docs/apps/build/graphql/basics/advanced#inline-fragments) 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

```graphql
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

```json
{
  "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.

***

## Identify 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

```graphql
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`:

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

***

## Create 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

```graphql
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

```json
{
  "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.

***

## Update a subdivision market

To change which regions a market targets, use [`marketUpdate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/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

```graphql
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 }
  }
}
```

***

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

***

## Next steps

* Learn about the [market types](https://shopify.dev/docs/apps/build/markets/market-types) you can create.

***