---
title: >-
  Query market hierarchies with the GraphQL Admin API - Shopify developer
  changelog
description: >-
  Shopify’s developer changelog documents all changes to Shopify’s platform.
  Find the latest news and learn about new platform opportunities.
source_url:
  html: 'https://shopify.dev/changelog/market-relationships'
  md: 'https://shopify.dev/changelog/market-relationships.md'
metadata:
  effectiveApiVersion: 2026-10
  affectedApi:
    - displayName: Admin GraphQL API
      handle: admin-graphql
  primaryTag:
    displayName: API
    handle: api
  secondaryTag:
    displayName: New
    handle: new
  indicatesActionRequired: false
  createdAt: '2026-09-11T13:16:27-04:00'
  postedAt: '2026-09-17T12:00:00-04:00'
  updatedAt: '2026-09-16T14:44:46-04:00'
  effectiveAt: '2026-09-12T12:00:00-04:00'
---

September 17, 2026

# Query market hierarchies with the GraphQL Admin API

DateSeptember 17, 2026

Version[2026-10](https://shopify.dev/changelog?api_version=2026-10)

FlagsNew

SurfacesAPI

Affected APIs[Admin GraphQL API](https://shopify.dev/changelog?api_type=admin-graphql)

The GraphQL Admin API now includes fields for querying and traversing a store’s market hierarchy in API version `2026-10`. Apps that use the `read_markets` access scope can retrieve parent-child relationships, navigate between related markets, and check if the asynchronously rebuilt relationship data has changed. No action is required for existing apps.

## What changed

The new [`marketRelationships`](https://shopify.dev/docs/api/admin-graphql/2026-10/queries/marketRelationships) query returns a connection of [`MarketRelationship`](https://shopify.dev/docs/api/admin-graphql/2026-10/objects/MarketRelationship) objects. Each relationship includes a `childMarket` and a nullable `parentMarket`. The `parentMarket` field is `null` if the `childMarket` is a root market.

The `Market` object now includes:

* [`parentMarkets`](https://shopify.dev/docs/api/admin-graphql/2026-10/objects/Market#field-Market.fields.parentMarkets): The market’s direct parent markets.
* [`parentMarketsCount`](https://shopify.dev/docs/api/admin-graphql/2026-10/objects/Market#field-Market.fields.parentMarketsCount): The number of direct parent markets.
* [`childMarkets`](https://shopify.dev/docs/api/admin-graphql/2026-10/objects/Market#field-Market.fields.childMarkets): The market’s direct child markets.
* [`childMarketsCount`](https://shopify.dev/docs/api/admin-graphql/2026-10/objects/Market#field-Market.fields.childMarketsCount): The number of direct child markets.

`MarketRelationship` IDs stay stable when Shopify rebuilds the relationship data as long as the direct relationship still exists after the rebuild. Connection cursors can change during a rebuild, so you should restart pagination after you detect a change.

Market relationships are rebuilt asynchronously after the market hierarchy changes. The [`marketRelationshipsStatus`](https://shopify.dev/docs/api/admin-graphql/2026-10/queries/marketRelationshipsStatus) query returns an opaque [`version`](https://shopify.dev/docs/api/admin-graphql/2026-10/objects/MarketRelationshipsStatus#field-MarketRelationshipsStatus.fields.version) value that you can compare with a previously retrieved value. A changed `version` value indicates that the materialized market relationships have advanced.

You should retrieve `version` before making a hierarchy-affecting change, poll it in separate requests, and refetch the relationships after the value changes. Don’t treat a `version` that you retrieve in the same request as `marketRelationships` as a snapshot identifier.

## Who’s affected

This change applies to apps that use GraphQL Admin API version `2026-10` or later and need to inspect or traverse market relationships.

Apps that use API versions before `2026-10` can’t query the new fields. Apps that don’t query markets are unaffected.

## Why this matters

You can reconstruct a store’s market hierarchy directly from market relationships, instead of inferring it from market conditions, customization state, or other indirect signals.

## What to do

No action is required for existing apps. Your existing integrations keep working on older API versions without changes.

To use the market hierarchy fields:

1. Use GraphQL Admin API version `2026-10` or later.
2. Confirm that your app has the `read_markets` access scope.
3. Query `marketRelationships`, or add the parent and child fields to a `Market` query.
4. If your app changes the market hierarchy, retrieve `marketRelationshipsStatus.version` before the change and poll it afterward in separate requests.
5. After `version` changes, restart pagination and refetch the relationship data. This ensures that your app uses the latest materialized relationships.

## Related docs

* [Market inheritance](https://shopify.dev/docs/apps/build/markets/new-markets/market-inheritance)
* [GraphQL Admin API reference for 2026-10](https://shopify.dev/docs/api/admin-graphql/2026-10)