Understanding the New applyResult Field in RolloutChange: What Developers Need to Know

Shopify’s GraphQL Admin API now returns an applyResult field on RolloutChange, letting apps track rollout outcomes in real time. Learn what changed, who it affects, and how to update your code to handle success, failure, and in‑progress states.

Understanding the New applyResult Field in RolloutChange: What Developers Need to Know
7 sections

Shopify’s latest GraphQL Admin API release (2027-01) introduces a game‑changing addition to the RolloutChange interface: the applyResult field. This new field gives developers a clear view of whether a rollout’s treatment changes were applied successfully, are still in progress, or failed – and why. In this post we’ll break down the update, explain who it matters to, and provide concrete steps to integrate the new data into your apps.

What’s New: The applyResult Field

Prior to the 2027-01 version, RolloutChange objects only described the changes themselves. Now each change node includes an applyResult object that reports the outcome of the most recent attempt to apply that change. If a rollout has never been applied, applyResult will be null. It also returns null when the staff member making the query lacks permission to read the changed resource, even if they have a valid online access token.

Fields Inside applyResult

The RolloutChangeApplyResult type contains three fields:

• status — IN_PROGRESS, SUCCESS or FAILURE. This tells you the current state of the apply operation.

• completedAt — A timestamp of when the attempt finished. It’s null while the operation is still running or if the system couldn’t record a time.

• errorCode — When status is FAILURE, this optional field explains why, using one of the following codes: RESOURCE_NOT_FOUND, VALIDATION_FAILED, LIMIT_EXCEEDED, INVALID_CHANGE or INTERNAL_ERROR.

Who Is Affected?

The change is purely on the developer side. Merchants who use apps that rely on rollout data will see more reliable behavior, but they don’t need to take any action themselves. Developers, theme engineers, and partners building custom checkout experiences or A/B‑testing tools must update their queries and error‑handling logic to take advantage of the new visibility.

Action Steps for Developers

  • Add the applyResult sub‑field to any RolloutChange queries. The field is optional, so existing queries won’t break, but you won’t get the new data unless you request it.
  • Update your permission scopes. The field uses the existing read_rollouts scope, so no new scope is required, but make sure your app’s token includes read_rollouts and that the staff member has read access to the underlying resources.
  • Implement robust status handling. Check applyResult.status and act accordingly:
  • • IN_PROGRESS – Show a pending state in your UI or schedule a retry after a short delay.

    • SUCCESS – Mark the change as live and optionally log the completedAt timestamp for audit trails.

    • FAILURE – Read errorCode to surface a meaningful message to the store owner or to trigger automated remediation (e.g., re‑validate the payload or alert support).

  • Gracefully handle null values. If applyResult is null, it means the rollout hasn’t been applied yet or the staff token can’t read the target resource. In those cases, either prompt the merchant to apply the rollout or verify token permissions.
  • Sample GraphQL Query

    Below is a minimal query that fetches the new applyResult information for the first ten changes of a rollout:

    graphql

    query GetRolloutChanges($id: ID!) {

    rollout(id: $id) {

    treatments {

    changes(first: 10) {

    nodes {

    id

    applyResult {

    status

    completedAt

    errorCode

    }

    }

    }

    }

    }

    }

    A typical response might look like this:

    {

    "data": {

    "rollout": {

    "treatments": {

    "changes": {

    "nodes": [

    {

    "id": "gid://shopify/RolloutChange/101",

    "applyResult": {

    "status": "SUCCESS",

    "completedAt": "2026-11-19T14:23:45Z",

    "errorCode": null

    }

    },

    {

    "id": "gid://shopify/RolloutChange/102",

    "applyResult": {

    "status": "FAILURE",

    "completedAt": "2026-11-19T14:25:12Z",

    "errorCode": "VALIDATION_FAILED"

    }

    }

    ]

    }

    }

    }

    }

    }

    Best Practices for Monitoring Rollouts

    • Store the applyResult.status and completedAt in your own database if you need historical reporting. This lets you compare rollout performance over time.

    • Implement exponential back‑off when polling for IN_PROGRESS results. Over‑polling can hit rate limits, especially on busy stores.

    • Map errorCode to user‑friendly messages. For example, show “The product you’re trying to update no longer exists” for RESOURCE_NOT_FOUND, or “You’ve reached the maximum number of active rollouts” for LIMIT_EXCEEDED.

    • Log INTERNAL_ERROR cases with request IDs so Shopify support can trace the issue if it persists.

    Conclusion & Next Steps

    The addition of applyResult to RolloutChange gives developers the visibility they’ve been missing when managing feature rollouts. By updating your GraphQL queries, handling the new status values, and communicating clear error messages to merchants, you can turn rollout failures into actionable insights and keep the shopping experience smooth.

    Ready to upgrade your app? Start by adding the applyResult field to your next GraphQL request, test against a staging store, and monitor the logs for any FAILURE cases. If you need help or have questions, drop a comment below or reach out to our developer support team. Happy coding!

    Tags
    Sources

    Related Articles

    Embedding YouTube & Vimeo Directly via File Reference Metafields in Shopify API 2027-01

    Embedding YouTube & Vimeo Directly via File Reference Metafields in Shopify API 2027-01

    Shopify’s 2027-01 API now lets file reference metafields store YouTube and Vimeo video URLs, unlocking seamless video embeds for merchants and developers. Learn what changed, who it affects, and how to implement the new feature today.

    November 20, 20265 min
    Why Your Shopify App Must Enable IP Allowlist by Tomorrow (Nov 20 2026)

    Why Your Shopify App Must Enable IP Allowlist by Tomorrow (Nov 20 2026)

    Shopify’s latest security deadline forces public and custom apps to add an IP allowlist. Learn what changed, who’s impacted, and step‑by‑step how to stay compliant before the November 20 cut‑off.

    November 19, 20265 min
    Show Image Swatches for Product Options via the Catalog API

    Show Image Swatches for Product Options via the Catalog API

    Shopify’s Catalog API now returns image swatches for product option values, letting developers display color or pattern previews directly in pickers. Learn what changed, who it impacts, and how to implement swatches with zero‑effort updates.

    November 19, 20264 min
    Multiple Error Reporting Now Available for Function Settings Extensions

    Multiple Error Reporting Now Available for Function Settings Extensions

    Shopify’s latest developer update lets function‑settings extensions return several validation errors at once, giving merchants instant feedback on every issue. Learn what changed, who it impacts, and how to implement the new AggregateError pattern today.

    November 19, 20265 min