See all services → Shopify Plus Partner
API Developer

Track Failed Rollout Changes With the New applyResult

GraphQL Admin API 2027-01 adds applyResult to RolloutChange, exposing status, completion time, and error code per change. It turns a partially applied rollout from a silent problem into something your tooling can catch.

Executive summary

What changed

RolloutChange now exposes applyResult, backed by a RolloutChangeApplyResult object with three fields. status is IN_PROGRESS, SUCCESS, or FAILURE. completedAt records when the attempt finished, and is null while in progress or if the time was not recorded. errorCode explains a failure when the reason is known, with values RESOURCE_NOT_FOUND, VALIDATION_FAILED, LIMIT_EXCEEDED, INVALID_CHANGE, and INTERNAL_ERROR.

Two null cases matter when building against this. applyResult is null before the first attempt to apply a change, which is expected rather than an error. It is also null when the request uses an online access token and the staff member cannot read the changed resource, so the same query can return different results depending on who is signed in. The field uses the existing read_rollouts scope, so no new permission is needed.

Why it matters

A rollout is usually the final step of an experiment: you have a winning treatment and want its changes to become permanent. The failure case is unintuitive, because a rollout is a set of changes and they do not necessarily all land. Without per-change status, a partial apply looks identical to a successful one, and the discrepancy surfaces later as a buyer seeing an experience nobody meant to ship.

The errorCode values are the useful part because they separate retry-worthy failures from design problems. INTERNAL_ERROR and LIMIT_EXCEEDED suggest trying again, while RESOURCE_NOT_FOUND, VALIDATION_FAILED, and INVALID_CHANGE usually mean the underlying resource moved or the change was never valid. For teams with a mature experimentation and CRO practice, that distinction is the difference between an automated retry and a ticket for a human.

There is a measurement angle too. If lift is calculated assuming a treatment shipped in full, a silently partial apply contaminates the result. Logging applyResult gives you an audit trail for the day a stakeholder questions a reported lift.

Role-specific impact

Use-case example

Real-world scenario

A retailer runs roughly 15 storefront experiments a quarter and applies the winners through rollouts. Twice last quarter a winning treatment appeared to ship while one of its changes did not, caught days later by a merchandiser who spotted a product page still showing the control layout. Each incident cost about half a day across two people. With applyResult, the deploy script now polls every change after an apply, writes status and errorCode to the experiment log, and alerts on any FAILURE, turning a multi-day blind spot into a notification within minutes.

Implementation checklist

  1. Move the integration to GraphQL Admin API version 2027-01.
  2. Add applyResult with status, completedAt, and errorCode to your rollout change queries.
  3. Confirm the calling app holds the read_rollouts scope, which is unchanged.
  4. Poll while status is IN_PROGRESS rather than reading once and assuming completion.
  5. Branch retry logic on errorCode, retrying INTERNAL_ERROR and LIMIT_EXCEEDED but escalating the rest.
  6. Treat a null applyResult as not yet attempted, and prefer an offline token where consistent visibility matters.
  7. Record status and completedAt in your experiment log so each apply has an audit trail.
  8. Alert on any FAILURE rather than relying on someone noticing the storefront.

FAQ

Q: Do we need to change anything if we apply rollouts manually in the admin?

A: No. This is an API addition for apps and tooling that query rollouts programmatically. It changes nothing about how rollouts behave, it only makes each change's outcome readable.

Q: Why does applyResult come back null for one of our staff users?

A: With an online access token, applyResult is null when that staff member cannot read the changed resource. It is a permissions outcome rather than a bug. Use an offline token for background jobs that need a consistent view.

Resources

The field reference for the new object and its error codes: RolloutChangeApplyResult.

Need guidance? Talk to Makro.