Executive summary
- What: GraphQL Admin API 2026-10 adds a marketRelationships query plus parent and child market fields on the Market object.
- Why: Apps can read a store's market hierarchy directly instead of reconstructing it from market conditions or customization state.
- Who: Merchants running multi-market international setups, and the apps, feeds, and middleware that need to know which market sits under which.
What changed
marketRelationships returns a connection of MarketRelationship objects. Each one carries a childMarket and a nullable parentMarket, where null identifies a root market. The Market object gains four companion fields: parentMarkets, parentMarketsCount, childMarkets, and childMarketsCount. Reading any of this requires the read_markets access scope.
The interesting detail is consistency. Shopify rebuilds relationship data asynchronously after a hierarchy change, so a fresh write is not immediately readable. A separate marketRelationshipsStatus query returns an opaque version value. Retrieve it before a hierarchy-affecting change, poll it in separate requests afterward, and refetch once it moves. Shopify is explicit that a version fetched in the same request as marketRelationships is not a snapshot identifier.
Relationship IDs stay stable across a rebuild as long as the direct relationship survives it. Pagination cursors do not, so restart pagination after a version change rather than resuming mid-stream. None of this affects existing apps, because the fields simply do not exist below 2026-10.
Why it matters
Market hierarchies are how large catalogues stay manageable across regions. A parent market carries shared configuration and child markets inherit and override it. Until now, anything outside the admin that needed to understand that structure had to guess, usually by comparing market conditions or reading where customizations had been applied. Guesses drift, and they drift silently.
For merchants running multi-market expansion with Shopify Markets, the value shows up in tooling rather than on the storefront. Pricing audits, catalogue coverage reports, feed generation, and translation QA all get simpler when the hierarchy is a first-class read. It also removes a class of integration bug where middleware held a mental model of the hierarchy that no longer matched reality.
Role-specific impact
- Marketers: Nothing changes in the admin. Expect better reporting from internal tools that can now group results by parent market rather than flattening every market into one list.
- Developers: Add read_markets if you do not already hold it, and treat the version value as your consistency gate. Do not assume a hierarchy write is readable on the next request.
- Store admins: Nothing to configure. Hierarchy changes now have an observable settling period that apps can detect, which is useful context when a report lags a restructure by a few minutes.
Use-case example
Real-world scenario
An apparel brand sells into 14 markets grouped under three regional parents. Its product feed service previously hardcoded that grouping in a config file, so each restructure needed a developer ticket. Twice in one year the config fell out of sync after a market moved, and the wrong regional pricing rules applied to roughly 900 SKUs for several days before anyone noticed. Reading marketRelationships at feed build time removes the config file entirely, and polling marketRelationshipsStatus.version means the feed waits out a restructure instead of publishing against a half-rebuilt hierarchy.
Implementation checklist
- Confirm the app holds the read_markets access scope.
- Move the integration to GraphQL Admin API version 2026-10 or later.
- Replace inferred hierarchy logic with marketRelationships, or add parentMarkets and childMarkets to existing Market queries.
- Capture marketRelationshipsStatus.version before any hierarchy-affecting mutation.
- Poll that version in separate requests after the change, and refetch relationships only once it differs.
- Restart pagination from the beginning after a version change rather than reusing cursors.
- Remove hardcoded market groupings from configuration once the live read is trusted.
FAQ
Q: Does this change anything for stores that are not on 2026-10?
A: No. The query and fields are version gated and additive. Apps on earlier versions keep working with no modification.
Q: Can the version value tell us exactly which relationships changed?
A: No. It is opaque and signals only that the materialized data has advanced. Use it as a trigger to refetch, then diff the relationships yourself.
Resources
marketRelationships query reference
Need guidance? Talk to Makro.