September 25, 2026 · Muhammad Rehan · More by Muhammad Rehan
Shopify's Market Hierarchy API Is Eventually Consistent
Shopify's new market hierarchy API is eventually consistent — here's the version-check-then-refetch pattern to use it safely.
What Shipped: Direct Market Hierarchy Traversal
On September 17, 2026, Shopify's GraphQL Admin API (version 2026-10) added a marketRelationships query, plus parentMarkets and childMarkets fields (and their *Count variants) on the Market object. Before this release, there was no direct traversal API for market parent/child relationships — apps had to infer hierarchy indirectly, from market conditions or other signals. For anything built on Shopify Markets or Shopify Plus multi-market setups — pricing engines, localized catalog tools, analytics dashboards — this is the first time market hierarchy is queryable directly.
Reading it is straightforward: Market.parentMarkets and Market.childMarkets each return a MarketConnection with standard cursor pagination, and marketRelationships returns every parent/child edge in the shop as a MarketRelationshipConnection. Both surfaces require read_markets for queries; mutating a market's structure requires read_markets plus write_markets.
The Part That's Easy to Miss: Eventual Consistency
Shopify's own reference docs are explicit about this: childMarkets, parentMarkets, their count fields, and the marketRelationships query are all documented as "Eventually consistent following a change in market hierarchy. See marketRelationshipsStatus." The mechanism is described plainly — the relationship graph is rebuilt asynchronously after a market, market condition, or market region changes, so a read taken immediately after a hierarchy change can still return the pre-change graph.
marketRelationshipsStatus.version is how a client detects that. It's an opaque UUID that "identifies the build of the market relationships that the API returns at the moment this field is read" — the value changes only when a rebuild advances the materialized graph, and is otherwise stable. That gives you a cheap way to tell staleness apart from a genuinely unchanged hierarchy, without guessing at a wait time Shopify has never published.
The Version-Check-Then-Refetch Pattern
The pattern follows directly from the eventual-consistency contract: read marketRelationshipsStatus.version before you fire a hierarchy-changing mutation — reparenting a market, adding a child market, and so on — then poll that same field in separate requests afterward. Don't trust marketRelationships, childMarkets, or parentMarkets until the version value you read has actually changed from the one you captured beforehand.
One more detail worth building into that retry loop: once the version changes, restart pagination from the beginning rather than resuming an in-flight cursor. Connections like MarketRelationshipConnection are backed by the materialized relationship table, so a cursor issued against the pre-rebuild graph isn't guaranteed to line up with the rebuilt one. For a pricing or catalog tool that caches hierarchy locally, skipping this check is exactly how you end up silently serving a stale parent/child structure after a merchant reparents a market — the API will still answer, it just won't tell you your read is out of date unless you ask it to.