Query market hierarchies with the GraphQL Admin API

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 query returns a connection of 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: The market’s direct parent markets.
parentMarketsCount: The number of direct parent markets.
childMarkets: The market’s direct child markets.
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 query returns an opaque 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:

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

Related docs

Was this page helpful?