- Mobile apps
- App Store
- Releases
- Alerts
App Store phased release: what to watch and when to pause
How App Store phased release works day by day, who really gets the update, what to monitor at 1%, 5% and 20%, and when to pause, with an API script.
- Author
- Extenify Team
- Published
- Reading time
- 14 min read

On this page
App Store phased release is the safest switch Apple gives you when you ship an iPhone update: instead of reaching everyone at once, the new version reaches a growing share of users over seven days, and you can pause it if something breaks. Most guides stop at the schedule. The harder part is knowing what to look at on each of those seven days, and what counts as a reason to pause, because the users you hear from first are not a random sample.
This guide covers how phased release works according to Apple's documentation, what it does not control, a day-by-day monitoring plan, clear pause rules, and a Node.js script that reads the phased release state and the new version's reviews through the App Store Connect API. It ends with a comparison against Google Play staged rollouts and Chrome Web Store percentage rollouts, for teams that ship to more than one store.
Key takeaways
- Phased release sends an update to users with automatic updates turned on over 7 days: 1%, 2%, 5%, 10%, 20%, 50%, then 100%.
- It does not limit manual updates or new downloads. Apple says the version "can be manually downloaded from the App Store by anyone at any time."
- You can pause for up to 30 days in total, as many times as you like, and resuming picks up on the day you left off.
- Your first reviews of a new version come mostly from people who update by hand, your most engaged users. Read them as an early warning, not as a verdict.
- Pause on crashes in a core flow, a jump in one- and two-star reviews for the new version, or broken payments or sign-in. For a severe bug, pausing is not enough: ship a fix.
How App Store phased release works
According to Apple's help page on how to release a version update in phases, selecting the option releases the update "gradually over 7 days" to "a random sample of users with automatic updates on eligible devices", who are not told they are part of it. The schedule is fixed:
| Day of phased release | Share of automatic-update users |
|---|---|
| 1 | 1% |
| 2 | 2% |
| 3 | 5% |
| 4 | 10% |
| 5 | 20% |
| 6 | 50% |
| 7 | 100% |
The App Store Connect API's PhasedReleaseState reference adds that phased release applies to "macOS and iOS devices with automatic updates enabled" and repeats that "users can also manually download the app version."
What phased release does not control
Three limits catch teams out:
- Manual updates and new downloads are not phased. Anyone who opens the App Store and taps Update gets the new version on day 1, and so does anyone who installs the app for the first time. Phased release only controls the automatic update.
- The schedule is not configurable. Apple documents one 7-day schedule. There is no custom percentage and no per-country rollout on the help page.
- It is for updates. The feature is described as releasing "a version update" in phases. A first release goes to everyone who downloads it.
That first point matters more than it looks. On day 1, the people running your new version are 1% of automatic updaters plus everyone who updates by hand. The second group is made of your most engaged users: they open the App Store, check for updates and often read release notes. They are also the people most likely to leave a review.
How to turn on, pause and finish a phased release
In App Store Connect, open the version you are preparing, find the Phased Release for App Store Automatic Updates section and choose to release the update over a 7-day period. The phased release starts when the version goes live.
Once it is running, Apple's help page sets the rules:
- Pause: "you may pause the release for up to 30 days, with no limit on the number of pauses." The 30 days are a total: pause for 10, resume, and you have 20 left.
- Resume: the release "will pick up on the day it was left off when it was paused."
- Release to all users: at any time once the version is Ready for Distribution, Release to All Users gives every device with automatic updates "the latest app version supported on the user's device."
- Removal from sale: if you remove the app from sale, including when your Developer Program membership lapses, "phased release will stop and won't be available for that version again." When the app comes back, the version goes to everyone immediately.
Pausing stops the automatic rollout. It does not take the version off the store, so manual updaters and new users keep getting it. App Store Connect has no button to go back to the previous build; the way out of a bad version is a new version, and Apple's App Review page lets you request an expedited review for a critical bug fix, with steps to reproduce the bug in the current version.
What to watch on each day of a phased release
The point of a phased release is to see problems while they are still small. That only works if you look at the right signal at the right time. Here is a plan that matches the schedule:
| Days | Who has the new version | What to look at | What it can tell you |
|---|---|---|---|
| 1 to 2 | 1 to 2% of automatic updaters, plus all manual updaters and new users | Crash reports, sign-in and purchase success, first reviews of the new version | Hard breakage in core flows |
| 3 to 4 | 5 to 10% plus manual updaters | One- and two-star share for the new version, support tickets, server errors by app version | Problems that hit a subset of devices, OS versions or accounts |
| 5 to 6 | 20 to 50% | Rating trend, retention of users on the new version, any spike in one theme in reviews | Quieter regressions: performance, UI changes people dislike |
| 7 | Everyone with automatic updates | The same, against the previous version's baseline | Whether the release is a net improvement |
Signals worth wiring up before release day
- Crashes by version. Xcode Organizer shows crash reports from users who share diagnostics, and most crash reporting SDKs tag every event with the app version. Compare the crash-free share of the new version with the previous one, not with zero.
- Reviews of the new version. The App Store Connect API has an endpoint that lists customer reviews for one App Store version, so you do not have to guess which version a review is about. The public customer reviews feed also carries the version on every entry; our guide to App Store review alerts shows how to read both.
- Your own backend. If your app sends its version in a request header, the share of requests from the new version is your real adoption curve. Error rates per version from the same logs are often the earliest warning you get.
- Ratings. The public rating moves slowly for an established app, so it is a late signal. Record it every day anyway; our guide to App Store rating history explains how to recover the average of only the new ratings from two snapshots.
Read early reviews with care
Because manual updaters dominate day 1 and day 2, early reviews of a new version are biased in two ways. Engaged users notice small changes, so a redesign can draw complaints that the wider audience never makes. They also hit edge cases first, so a real bug shows up here before it shows up in crash numbers. The practical rule: treat a cluster of reviews describing the same broken behavior as a reason to investigate immediately, and treat a general dip in stars from a handful of reviews as noise until days 3 and 4 confirm it.
When to pause a phased release
Decide the rules before release day, so nobody argues about them while users are affected. A set that works for most apps:
- Pause immediately if sign-in, purchase, sync or the core action of the app fails for users on the new version, or if the crash-free share drops clearly below the previous version's.
- Pause and investigate if the share of one- and two-star reviews for the new version is at least 15 percentage points above the 30 days before the release, with at least 20 reviews on each side. Smaller samples swing too much to act on.
- Keep going if the only complaints are about a change you made on purpose, and the crash and error numbers are flat. That is feedback for the next version, not a rollback.
- Release to all users early only when crash, error and review numbers have been flat for several days at 10% or more. Finishing early saves a few days; it rarely saves anything else.
Remember what a pause does and does not do. It protects the users who would have received the update automatically. Everyone else can still install it, so for a severe bug the real fix is a new version, submitted as soon as you have it.
Automate the check with the App Store Connect API
The App Store Connect API exposes the phased release as its own resource, appStoreVersionPhasedReleases, with four attributes: phasedReleaseState, currentDayNumber, startDate and totalPauseDuration. The state is INACTIVE, ACTIVE, PAUSED or COMPLETE. The useful endpoints, all from Apple's reference:
| Task | Request |
|---|---|
| Read a version's phased release | GET /v1/appStoreVersions/{id}/appStoreVersionPhasedRelease |
| Turn phased release on for a version | POST /v1/appStoreVersionPhasedReleases |
| Pause, resume or release to all | PATCH /v1/appStoreVersionPhasedReleases/{id} with a new phasedReleaseState |
| Cancel a phased release that has not started | DELETE /v1/appStoreVersionPhasedReleases/{id} |
| Reviews of one version | GET /v1/appStoreVersions/{id}/customerReviews |
The script below runs once a day during a rollout. It finds the live iOS version, prints the phased release day and state, compares the one- and two-star share of that version's reviews with the 30 days before the release started, and pauses the release only when you pass --pause and the rule from the previous section fires. It needs Node.js 18 or newer and no packages: the ES256 token is signed with node:crypto. Create a team API key under Users and Access in App Store Connect and pass the key ID, issuer ID and the contents of the .p8 file as environment variables.
// phased-release-watch.mjs: read today's phased release state and the new version's reviews,
// and pause the release when low-star reviews jump. Pass --pause to let it act.
// Env: ASC_KEY_ID, ASC_ISSUER_ID, ASC_PRIVATE_KEY (contents of the .p8 file), APP_ID
import { createPrivateKey, sign } from 'node:crypto';
const API = 'https://api.appstoreconnect.apple.com/v1';
const b64url = (input) => Buffer.from(input).toString('base64url');
export function appStoreToken({ keyId, issuerId, privateKey }) {
const now = Math.floor(Date.now() / 1000);
const header = b64url(JSON.stringify({ alg: 'ES256', kid: keyId, typ: 'JWT' }));
const payload = b64url(JSON.stringify({ iss: issuerId, iat: now, exp: now + 15 * 60, aud: 'appstoreconnect-v1' }));
// JWTs need the raw r||s signature, not the DER encoding Node uses by default.
const signature = sign('sha256', Buffer.from(`${header}.${payload}`), {
key: createPrivateKey(privateKey),
dsaEncoding: 'ieee-p1363',
});
return `${header}.${payload}.${b64url(signature)}`;
}
async function asc(path, init = {}) {
const token = appStoreToken({
keyId: process.env.ASC_KEY_ID,
issuerId: process.env.ASC_ISSUER_ID,
privateKey: process.env.ASC_PRIVATE_KEY,
});
const res = await fetch(`${API}${path}`, {
...init,
headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', ...init.headers },
});
if (res.status === 404) return null;
if (!res.ok) throw new Error(`${init.method ?? 'GET'} ${path}: HTTP ${res.status} ${await res.text()}`);
return res.status === 204 ? null : res.json();
}
function lowStarShare(reviews) {
if (reviews.length === 0) return null;
return reviews.filter((r) => r.attributes.rating <= 2).length / reviews.length;
}
const appId = process.env.APP_ID;
const versions = await asc(
`/apps/${appId}/appStoreVersions?filter[platform]=IOS&filter[appVersionState]=READY_FOR_DISTRIBUTION&limit=1`,
);
const version = versions?.data?.[0];
if (!version) throw new Error('No live iOS version found');
const phased = (await asc(`/appStoreVersions/${version.id}/appStoreVersionPhasedRelease`))?.data;
if (!phased) {
console.log(`${version.attributes.versionString}: no phased release`);
process.exit(0);
}
const { phasedReleaseState, currentDayNumber, totalPauseDuration, startDate } = phased.attributes;
console.log(`${version.attributes.versionString}: ${phasedReleaseState}, day ${currentDayNumber}, paused ${totalPauseDuration} days so far`);
// Reviews of the new version against the app's reviews from the 30 days before the release started.
const newReviews = (await asc(`/appStoreVersions/${version.id}/customerReviews?sort=-createdDate&limit=200`))?.data ?? [];
const start = new Date(startDate);
const before = ((await asc(`/apps/${appId}/customerReviews?sort=-createdDate&limit=200`))?.data ?? []).filter((r) => {
const created = new Date(r.attributes.createdDate);
return created < start && created > new Date(start.getTime() - 30 * 86400e3);
});
const now = lowStarShare(newReviews);
const baseline = lowStarShare(before);
console.log(`new version: ${newReviews.length} reviews, 1-2 stars ${now === null ? 'n/a' : `${Math.round(now * 100)}%`}`);
console.log(`30 days before: ${before.length} reviews, 1-2 stars ${baseline === null ? 'n/a' : `${Math.round(baseline * 100)}%`}`);
const enoughData = newReviews.length >= 20 && before.length >= 20;
const worse = enoughData && now - baseline >= 0.15; // 15 percentage points more 1-2 star reviews
if (worse && phasedReleaseState === 'ACTIVE') {
console.log('Low-star share is up by 15 points or more.');
if (process.argv.includes('--pause')) {
await asc(`/appStoreVersionPhasedReleases/${phased.id}`, {
method: 'PATCH',
body: JSON.stringify({ data: { type: 'appStoreVersionPhasedReleases', id: phased.id, attributes: { phasedReleaseState: 'PAUSED' } } }),
});
console.log('Phased release paused.');
}
}
A few notes before you schedule it:
- What we tested. We checked the token locally: the header and claims match Apple's token requirements and the 64-byte signature verifies against the key's public half. The endpoints, filters and states come from Apple's API reference; run the script without
--pauseagainst your own account first and read its output for a day or two before you let it act. - Limits. Both review endpoints return at most 200 reviews per page. For an app with more than 200 reviews in 30 days, follow
links.nextfor the baseline. - Keep pausing human for core breakage. The script covers one signal. Crashes and failed purchases come from your crash reporter and your backend; wire those to the same channel and let a person press pause.
- Scheduling. Once a day is enough, since the schedule advances once a day. Our guide to a reliable Node.js cron job covers running it on time and catching up after downtime, and the Slack webhook in Node.js guide shows how to post the output where your team will see it.
App Store phased release vs Google Play staged rollout vs Chrome Web Store
If you ship the same product to several stores, the rollout tools look similar and behave differently:
| App Store phased release | Google Play staged rollout | Chrome Web Store percentage rollout | |
|---|---|---|---|
| Who is in the rollout | Users with automatic updates; manual updates and new downloads always get the new version | New and existing users, chosen at random | A percentage of users |
| Schedule | Fixed 7 days: 1, 2, 5, 10, 20, 50, 100% | You set the percentage; it never increases on its own | You set the percentage and raise it without a new review |
| Stop | Pause up to 30 days in total | Halt; users who already have it stay on it | Roll back to the last version that was at 100% |
| Eligibility | Any update | Any update | Items with over 10,000 seven-day active users |
The Google Play column comes from Play Console help on staged rollouts, which notes that "your app's staged rollout percentage won't increase automatically" and that halting means "no additional users will receive the app version." The Chrome column comes from Google's guide to updating a Chrome Web Store item and its rollback page. Browser extensions have one more trap: an update that adds a permission warning disables the extension until each user accepts, which our guide to Chrome extension weekly users dropping covers.
Watch every release from the outside too
Your own dashboards tell you how your users react. The store tells you what everyone else sees: the version on the listing, the rating in each country and the reviews coming in. Extenify records those every day for App Store and Google Play apps, next to your Chrome, Edge and Firefox extensions, puts version markers on the same timeline as installs, rating and rank, and sends an alert for rating drops, fresh one-star reviews and new versions to email, Slack, Discord, Telegram or Microsoft Teams. Because the data is public, the same timeline works for a competitor's releases. Our guide to App Store version history explains what the store keeps and what you need to record yourself, and what to watch in the week after a release gives the general checklist. Every plan starts with a free trial; see Extenify pricing.
Frequently asked questions
Does App Store phased release apply to new users?
No. Phased release controls automatic updates only. Apple says apps and updates in phased release "can be manually downloaded from the App Store by anyone at any time", so new downloads and manual updates get the new version from day 1.
Can I choose the percentages or the length of a phased release?
No. Apple documents a single 7-day schedule: 1%, 2%, 5%, 10%, 20%, 50% and 100%. You can pause it, and you can release to all users early, but you cannot set your own steps.
What happens when I pause a phased release?
No more automatic updates go out, and users who already have the version keep it. The version stays on the store for manual updates and new downloads. You can pause for 30 days in total, and when you resume, the release continues from the day where you paused.
What happens if I release a new version during a phased release?
Apple's documentation does not spell it out. In an Apple Developer Forums thread, developers reported that the new version replaces the previous one when it goes live, whatever release option the earlier one used. Turn on phased release for the fix too if you still want a gradual rollout.
Can I use phased release for the first version of an app?
No. It is a way to release a version update. The first version goes to everyone who downloads it, so test it with TestFlight before launch instead.
Can I see whether a competitor is using phased release?
Not directly. The store does not show rollout progress. Because anyone can download a phased update by hand, the listing offers the new version from the day it goes live, so you can start following its reviews and rating right away.
Summary
App Store phased release spreads an update over seven days for users with automatic updates, while manual updaters and new users get it immediately. Use those seven days on purpose: watch crashes and core flows on days 1 and 2, the low-star share of the new version's reviews on days 3 and 4, and quieter regressions after that. Decide your pause rules before release day, remember that a pause does not remove the version, and automate the daily check with the App Store Connect API so the numbers reach you without anyone having to look.
Image credits
- Cover photo: Modern stone upwards staircase between white walls by blorjo on the WordPress Photo Directory, CC0.


