Executive summary
- What: Admin GraphQL API version 2026-10 adds a rollouts query, a rollout lookup by ID, and Rollout webhooks, behind a new read_rollouts access scope.
- Why: Apps can finally see the coordinated launches, A/B tests and temporary events that change discounts, catalogs, themes, and checkout and accounts configurations.
- Who: App and integration developers whose logic depends on knowing what is actually live for buyers.
What changed
Rollouts are how merchants run sales events, permanent launches and A/B tests by serving treatments to a configured share of buyers. Until now they were invisible to apps. The new surface lets an app list and search Rollouts with the root rollouts query, fetch one directly with rollout by ID, and read what each treatment changes across discounts, catalogs, themes, and checkout and accounts configurations. Schedule and allocation fields are readable: planned activation and conclusion times, configured trafficAllocation, current effectiveTrafficAllocation, and treatment split values. Webhooks cover lifecycle changes, effective-allocation changes and resource changes, so an integration can refetch on notification instead of polling. Access requires the read_rollouts scope, existing resource scopes still govern the underlying payloads, and installed apps may need merchant reauthorization.
Why it matters
One detail deserves more attention than the rest: configured allocation is not effective reach. The trafficAllocation field is what the merchant set. The effectiveTrafficAllocation field is what the Rollout actually receives once mutex group constraints with other active Rollouts are applied. An integration that reads the configured number and reports it as the share of buyers affected will be wrong whenever two Rollouts overlap, and it will be confidently wrong, which is the harder kind to catch. Any reporting or decision logic should read the effective value.
The broader value is explanatory. When a merchant asks why a discount, catalog or theme behaved differently from what the admin suggested, a Rollout is now a readable answer rather than a guess. For anyone operating a middleware layer between Shopify and downstream systems, that is one more source of silent divergence brought into view.
Role-specific impact
- Marketers: Experiment and event data can flow into reporting tools, so test results are attributed to the Rollout that produced them instead of inferred from a date range.
- Developers: Add read_rollouts, plan for merchant reauthorization on existing installs, subscribe to the Rollout webhooks, and use effectiveTrafficAllocation wherever you express reach.
- Store admins: Expect connected tools and dashboards to start reflecting Rollouts, which should cut the time spent explaining why a report and the storefront disagreed.
Use-case example
Real-world scenario
A footwear merchant on Shopify Plus runs two overlapping Rollouts during a seasonal event: a themed homepage at 50 percent and a discount test at 50 percent, both in the same mutex group. Its analytics middleware reads configured allocation and reports each as reaching half of buyers, so the conversion comparison looks internally inconsistent and the marketing team stops trusting the test. Reading effectiveTrafficAllocation instead shows the real split and makes the results usable. Subscribing to the effective-allocation webhook keeps that figure current when the merchant adjusts the event mid-flight, which on a two-week event happened three times.
Implementation checklist
- Decide whether your app needs Rollout visibility, which it does if it reads discounts, catalogs, themes, or checkout and accounts configurations.
- Add read_rollouts to your app's scopes and prepare a reauthorization path for existing installations.
- Move the integration to Admin GraphQL API version 2026-10.
- Use the rollouts query to discover active Rollouts, and the rollout lookup when you already hold an ID.
- Read effectiveTrafficAllocation, not trafficAllocation, anywhere you express or report buyer reach.
- Subscribe to the lifecycle, effective-allocation and resource-change webhooks, and refetch the affected Rollout on each event.
- Test with two overlapping Rollouts so the mutex behaviour is exercised before release.
FAQ
Q: Why do existing installs need reauthorization?
A: read_rollouts is a new scope. Merchants granted only the scopes your app requested at install time, so an app adding this one needs consent again before Rollout data is returned.
Q: Can we poll instead of using the webhooks?
A: You can, but effective allocation changes when other Rollouts start or stop, which is outside your control and hard to predict. The webhooks tell you exactly when to refetch, which is cheaper and more accurate.
Resources
Need guidance? Talk to Makro.