Styxis
Company
Knowledge

Shopify market relationships: restart pagination when the version changes

Stable relationship IDs do not imply stable cursors during a rebuild. Separate collection generations before accepting the hierarchy.

A stable relationship ID is not a stable read generation

Relationship identity and pagination-cursor stability are different properties. After detecting a relationship-version change, restart pagination from the beginning. A list assembled partly from the old hierarchy and partly from the new one may still contain plausible parent-child pairs. Its collection history belongs in the handoff. [1, 2, 3]

The announcement distinguishes relationships from cursors

Shopify's 2026-09-17 announcement introduced marketRelationships and relationship-status queries for 2026-10. It states that a relationship ID remains stable if the direct relationship survives a rebuild, while cursors may change. Relationships rebuild asynchronously, and parentMarket may be null for a root market. A missing parent is therefore not a reason to reject every root row as incomplete. [1]

Separate version polling from relationship reads

The handoff owner should preserve the pre-change version, the new version observed in a separate request and the cursor-restart record. Do not accept relationships from different collection generations as one list. Record read_markets permission and the API version as well. The announcement warns against treating a version returned in the same request as the relationships as a snapshot identifier. Adding a version column does not itself make a read atomic. [1, 3]

Opaque versions do not need an ordering comparison

Suppose an illustrative collection observes opaque version vA before a change and vB in a separate request afterward. Their difference requires restart state true. An actual collection log with true satisfies the action condition of beginning a new generation. A false record means the old cursor was continued, so do not accept that mixed list. There is no need to calculate whether vB is larger than vA. This fixture explains a behavioral contract; it is not an executed server rebuild. [1, 3]

A check cannot manufacture a collection log

ExpressionValidator in Truthound Core 3.3.2 accepts a filter_expr for the acceptance condition on a prepared table of version changes and restart states. Nonconforming rows become investigation or recollection work for the collector. Truthound does not complete a rebuild or validate a server cursor. Without a version change, follow the waiting and polling policy instead of requiring unconditional restarts. If the logs are missing, obtain that evidence first. [1, 2, 3]

Application conditions

Use 2026-10 or later with read_markets permission. Observe the version before a hierarchy change and afterward in separate requests. Derive restart state from actual collection logs.

Alternatives

If the version has not changed, hold collection according to the waiting and polling policy. After a change, recollect every page as a new generation.

Limitations

  • A version obtained in the same request is not an atomic snapshot identifier for the relationship list. Truthound does not complete asynchronous rebuilds or verify server-cursor validity.

Evidence

Event checked
Subject checked
Modified