Admin GraphQL API / For developers

Rollouts you can read and track
Queries and webhooks now in the Admin GraphQL API

Apps can now discover Rollouts (planned launches, experiments, and limited-time events), read their schedules, traffic allocations, and the resources they change, and get notified when a Rollout changes. Rollouts cover discounts, catalogs, themes, and checkout and account settings.

On this page
  1. What's changing (in 30 seconds)
  2. Explainer: What's inside a Rollout and what you can read
  3. 4 new capabilities
  4. Schedule and allocation: configured and effective values differ
  5. Staying in sync: webhook → refetch
  6. Access requirements (scopes and re-authorization)
  7. 5 key points for developers
  8. 3 business use cases
  9. One-line summary for proposals

1What's changing

A Rollout spans settings such as discounts, catalogs, themes, and checkout and accounts. It is the unit forplanned launches, experiments, and limited-time events.
Apps can now use the Admin GraphQL API to search for and retrieve Rollouts and read their contents,and receive changes via webhooks.

From the app's perspective: before

The announcement doesn't describe the previous state. It only says that apps can now discover and read Rollouts.

From the app's perspective: now

Apps can list and search Rollouts, fetch them by ID, and read each treatment's changes, the schedule, and the allocation. They can receive webhooks for lifecycle events, effective allocation changes, and resource changes.

2Explainer: What's inside a Rollout and what you can read

Rollout Schedule Scheduled start / end times Traffic allocation trafficAllocation (configured value) effectiveTrafficAllocation (current value) Treatments split value (split ratio) Each treatment affects Discounts Catalogs Themes Checkout and account settings Your app Query : rollouts / rollout(id:) Webhooks: get notified of changes Scope: read_rollouts Underlying resources also require their existing scopes
What is a Rollout? : The article describes it as "a planned launch, experiment, or time-limited event spanning discounts, catalogs, themes, and checkout and account settings." How merchants create and manage them is not covered in this article.

34 new capabilities

Find and read
rollouts to list and search
rollout(id:) to fetch directly
What changes
Per treatment
Impact on 4 resource types
Schedule and allocation
Scheduled start/end, configured allocation
Effective allocation, split values
Stay up to date
Subscribe to Rollout webhooks and
re-fetch affected Rollouts

4Schedule and allocation: "configured" and "effective" values are different

Scheduled start time Scheduled end time planned activation ~ conclusion trafficAllocation Configured allocation Configured value effectiveTrafficAllocation Current effective allocation Effective value ≠ not necessarily equal

* Bar lengths are illustrative. The article does not give specific values or the conditions under which the two differ.

The article explicitly "the configured allocation alone does not determine effective reach" warns. If you need to know how far it actually reaches, check effectiveTrafficAllocation instead.

5Staying in sync: webhook → re-fetch

1

Subscribe to Rollout webhooks

Notifications come in 3 categories: lifecycle, effective allocation, and resource changes.

2

Receive notifications

Use them as a trigger to find out which Rollout changed.

3

Refetch affected Rollouts

Article recommendation: refetch affected Rollouts to keep synced data up to date.

Notification categoryWhat it tells youSpecific topic name
LifecycleChanges to Rollout stateNot specified (see API reference)
Effective allocationChanges to effective allocationNot specified (see API reference)
Resource changesChanges to the resources a Rollout modifiesNot specified (see API reference)

6Access requirements (scopes and reauthorization)

Required

read_rollouts

The scope to request for access to Rollout data.

Also applies

Existing resource scopes

Resource payloads inside a Rollout, such as discounts, are subject to their own existing scopes.

Note

Reauthorization may be required

Existing installations may require merchant reauthorization.

For apps that read discounts, the separate guide "Update your app to account for discount Rollouts" covers discount-specific integration and compatibility behavior. This article doesn't list the supported API versions.

75 key points for developers

READ

1. This release is "read + notify"

The article covers queries (rollouts / rollout(id:)) and webhooks. It doesn't mention mutations for creating or updating Rollouts.

≠

2. Configured allocation ≠ effective reach

trafficAllocation alone doesn't tell the whole story. Read current impact from effectiveTrafficAllocation, and the allocation across treatments from the split values.

3. Webhooks are the signal; refetch for the truth

The article advises refetching affected Rollouts after a notification. It's safer not to build state from the notification payload alone.

4. Scopes work in two layers

read_rollouts is needed, and existing scopes also apply to the resource payloads inside. Design your scopes and error handling on the assumption that with only one, some data won't be visible.

%OFF

5. Discount apps: read the dedicated guide

For apps that read discounts, "Update your app to account for discount Rollouts" is available and also coverscompatibility behavior. If you have an existing discount integration, review it whether or not you adopt this feature. Plan the reauthorization flow for existing installations as well.

83 practical use cases for your business

%OFF
USE CASE 1

Keeping discount apps in sync with Rollout-driven discounts

Challenge
Apps that read discounts (for price display, reporting, etc.) can't see limited-time or experimental discounts created by Rollouts, so their displays and totals may drift.
Approach
read_rollouts added → rollouts to identify Rollouts that affect discounts → re-fetch the relevant Rollout when a webhook arrives.
Impact
Apps can also see when and at what allocation a discount applies, which makes it easier to trace the cause of support inquiries and inconsistencies.
Tech notes
Follow the dedicated guide for discount-specific behavior. Existing installs may need to re-approve access, so prepare a merchant-facing notice first.
Configured vs. effective
USE CASE 2

A dashboard that shows the effective reach of experiments and launches

Challenge
When running experiments on themes or checkout settings, you can't see the gap between the configured allocation and the allocation actually reaching customers, so results are easy to misread.
Approach
For each Rollout, fetch trafficAllocation,effectiveTrafficAllocation, treatment split values, and scheduled start/end times, and display them side by side. Update them via the effective-allocation webhook.
Impact
See experiment progress in one list without clicking through the admin, and attach the correct assumption (the actual allocation) to your reports.
Tech notes
The article states plainly that configured allocation alone doesn't determine effective reach, so make that explicit in the UI too. It doesn't say when the two diverge, so don't add any estimation logic.
USE CASE 3

A change calendar and operational alerts for sales and limited-time events

Challenge
For events that switch discounts, catalogs, and themes at the same time, stakeholders don't share a clear view of what changes when, leaving support, inventory, and ad operations playing catch-up.
Approach
Fetch each Rollout's scheduled start/end times and the resources each treatment affects, then build a calendar. Send notifications to Slack or similar via lifecycle and resource-change webhooks.
Impact
Prevents missed checks before an event starts and speeds up handling of inquiries at switchover.
Tech notes
Always re-fetch when a notification arrives and refresh the display with the latest state. Check the API reference for specific webhook topic names and payload formats (not covered in this article).

9One-line summary for proposals

"Rollouts that span discounts, catalogs, themes, and checkout settings can now be read by
apps via read_rollouts and tracked with webhooks.
For the actual allocation, check effectiveTrafficAllocation, and always re-fetch when a notification arrives."