Shopify merchants and developers constantly juggle discounts, theme updates, catalog changes, and checkout experiments. Until now, apps had limited visibility into those coordinated launches—known as Rollouts—making it hard to stay in sync with a store’s live configuration. The recent Developer Changelog release adds dedicated Rollout queries and webhook subscriptions to the Admin GraphQL API, giving apps the tools they need to discover, track, and respond to every rollout event in real time.
What’s New in the Rollouts API
Who Is Affected – Developers vs. Merchants
The update is primarily a developer‑facing change, but its ripple effects reach merchants too. Any public or custom app that reads discounts, catalogs, themes, or checkout settings will now receive richer context about when and why those resources change. Merchants benefit indirectly through more stable apps that can react to experiments (e.g., A/B pricing tests) without manual intervention.
How to Query Rollouts with GraphQL
First, request the read_rollouts scope when installing or updating your app. Existing installations may need a re‑authorization prompt.
A basic query to list active Rollouts looks like this:
graphql
query GetRollouts($first: Int, $after: String) {
rollouts(first: $first, after: $after) {
edges {
node {
id
name
status
scheduledActivation {
startDate
endDate
}
trafficAllocation {
percentage
}
treatments {
name
discountChanges {
discountId
newValue
}
}
}
}
}
}
Replace $first and $after with pagination values as needed. To fetch a single Rollout by ID:
graphql
query GetRollout($id: ID!) {
rollout(id: $id) {
id
name
effectiveTrafficAllocation {
percentage
}
treatments {
name
catalogChanges {
productIds
action
}
}
}
}
Understanding Schedules, Allocation, and Treatments
effectiveTrafficAllocation when deciding how much of your logic should be applied.Subscribing to Rollout Webhooks
Shopify now emits three webhook topics for Rollouts:
rollouts/lifecycle – Fires on creation, activation, pause, and deletion.rollouts/effective_allocation – Notifies when the effective traffic allocation changes.rollouts/resource_change – Alerts when the underlying resource payload (discount, catalog, theme, etc.) is altered.Register them just like any other admin webhook:
POST https://your-app.com/webhooks
{
"webhook": {
"topic": "rollouts/resource_change",
"address": "https://your-app.com/webhooks/rollout",
"format": "json"
}
}
When a webhook arrives, immediately refetch the affected Rollout (rollout(id:)) to get the latest treatment details and apply any necessary updates to your store‑side data.
Action Checklist for Your Apps
effectiveTrafficAllocation before applying discount calculations.rolloutCreate (available in the API reference).Conclusion
The new Rollout queries and webhook events turn what used to be a black box into a transparent, programmable workflow. By adding a few lines of GraphQL and webhook registration, your app can stay in lockstep with Shopify’s coordinated launches, reduce support tickets, and deliver a smoother experience for merchants. If you haven’t yet upgraded, start with the OAuth scope change and a simple rollout list query today—your future‑proof app will thank you.
