3 displays per person per 365 days

Review Prompt Planner

Apple gives you three prompts per person per year and decides itself whether any of them appears. This is a worksheet for choosing the moments before you wire them up, checked against what Apple actually published. Your answers stay in your browser.

Apple never tells you whether the prompt was shown. The API returns nothing — no boolean, no completion handler, no callback — and Apple documents none. It requests a review “if appropriate”, and StoreKit decides.

So there is no response rate, no prompt-to-rating ratio and no expected number of ratings, here or anywhere else: the denominator does not exist. Anyone quoting one for the system prompt is quoting something nobody can measure. This page will not print a figure it cannot stand behind, and there is no score on it for the same reason — every question below is a judgement about an app it has never seen.

This page is about the mechanics, not the need. The rating benchmark is the one that answers whether you are short of ratings in the first place — it ranks your rating count against the apps sharing your search result, because 4,000 ratings is excellent for a small app and dismal for a big one.

What you call

Guideline 5.6.1 requires the system API and says custom review prompts will be disallowed. There is more than one way in and they are one mechanism underneath — StoreKit decides, the system draws the prompt.

  • @Environment(\.requestReview)current

    An instance that tells StoreKit to request an App Store rating or review, if appropriate.

    iOS 16.0+, iPadOS 16.0+, Mac Catalyst 16.0+, macOS 13.0+, visionOS 1.0+

    The SwiftUI route. The environment value hands you a RequestReviewAction, which you call directly — it declares callAsFunction(), so the call site is just requestReview().

    Apple’s reference
  • AppStore.requestReview(in:)current

    Tells StoreKit to request an App Store rating or review from the user, if appropriate, using the specified scene.

    iOS 16.0+, iPadOS 16.0+, Mac Catalyst 16.0+, visionOS 1.0+ (UIWindowScene); macOS 13.0+ (NSViewController)

    The UIKit and AppKit route, and the replacement Apple names in the deprecation message on the old class.

    Apple’s reference
  • SKStoreReviewControllerdeprecated

    An object that controls the process of requesting App Store ratings and reviews from customers.

    introduced iOS 10.3 / macOS 10.14; deprecated iOS 18.0, iPadOS 18.0, Mac Catalyst 18.0, macOS 15.0, visionOS 2.0

    Apple gives two replacement pointers for it and this page reports both rather than choosing: the platform deprecation message says "Use AppStore.requestReview(in:)." and the page's own deprecation summary says "Use RequestReviewAction instead." Note that Apple's marketing page at developer.apple.com/app-store/ratings-and-reviews/ still names this class as the API to use — the documentation is the newer of the two.

    Apple’s reference

What the system does, in Apple’s words

Quoted rather than paraphrased, because these four sentences decide what any plan below can actually achieve.

Although you normally call this method when it makes sense in the user experience flow of your app, App Store policy governs the actual display of a rating and review request view.

— StoreKit — RequestReviewAction

If the person hasn’t rated or reviewed your app on this device, StoreKit displays the ratings and review request a maximum of three times within a 365-day period.

— StoreKit — RequestReviewAction

If the person has rated or reviewed your app on this device, StoreKit displays the ratings and review request if the app version is new, and if more than 365 days have passed since the person’s previous review.

— StoreKit — RequestReviewAction

Because this API may not present an alert, don’t call it in response to a button tap or other user action. It’s up to your app to decide on the best timing for requesting reviews.

— StoreKit — RequestReviewAction

Two consequences worth sitting with. Wiring up more call sites does not buy more prompts — it only changes which ones spend the year’s 3 displays. And a “Rate us” button is the one thing Apple names outright: because the call may show nothing at all, a tap that produces no visible response reads as a broken button. For that case Apple documents a different mechanism — a persistent link to your product page with action=write-review appended, which always opens something.

People can review your app at any time on the App Store. To make it easier for people to leave reviews, you may include a persistent link to your App Store product page in your app’s settings or configuration screens. Append the query parameter action=write-review to your product page URL to automatically open the App Store page where users can write a review.

— StoreKit — RequestReviewAction

Your moments

Write down each point in the app where a prompt could fire: what the person has just done, and why that is a moment of satisfaction rather than a convenient hook. Five questions open under each one, and every one of them exists because of a sentence Apple published — the sentence is shown when your answer runs into it.

No moments yet. Add the first one below — most apps have fewer good ones than they think, which is the useful discovery here.

Against Apple’s rules

Four of these are guideline violations and Apple states the consequence itself; two are design guidance and are labelled as such. They are not the same thing and this page does not flatten them into one. Answer for the plan as a whole — an unanswered question stays unanswered here and is never read as a no.

  • Sentiment gating

    guideline

    Does anything ask how they feel first, and only prompt the happy ones?

    A "Enjoying the app?" dialog, a thumbs up/down, an NPS question, or any branch that sends unhappy users to a support form instead of the prompt.

  • Incentivising

    guideline

    Is anything offered in exchange for a rating or review?

    Coins, credits, an unlock, a free month, entry into a draw — anything of value contingent on rating.

  • Forcing or blocking

    guideline

    Does anything in the app become unavailable until they rate?

    A gate, a paywall, a dismissible-only-by-rating dialog, a "rate to continue" step.

  • Custom review UI

    guideline

    Does your own interface collect the star rating or the review text?

    Your own star row, your own review box, or a third-party SDK that draws a review prompt rather than calling the system one.

  • Repeating on dismissal

    guidance

    Does a dismissed prompt come back sooner because it was dismissed?

    Retry timers, "ask me later" queues, or re-arming the call on the next launch after a dismissal.

  • Spacing between requests

    guidance

    Is there at least a week or two between any two requests to the same person?

    Across every moment, not per moment — the person experiences one app, not five triggers.

On sentiment gating — the “Enjoying the app?” dialog that only shows the real prompt to people who tap the happy face. Apple’s preamble to section 3 lists filtered feedback alongside paid, incentivized and fake, and 5.6.3 forbids manipulating “any element of the App Store customer experience such as charts, search, reviews”. Reading a happy-users-only pre-filter as filtered feedback is our reading of those two sentences, not a separate rule Apple wrote — so both are quoted above and you can judge them yourself.

Independently of any of that, it does not do what it is sold as doing. StoreKit decides whether the prompt appears; screening for happy users only shrinks the pool of people your 3 annual displays can be spent on. Nobody here will tell you to gate on how the user feels.

Worth a second look

Questions against Apple’s own wording, not judgements about your app. Nothing here adds up to a total — a passing mark on a page where one item can end a developer account would be an invitation to stop reading.

Unanswered: Sentiment gating

Does anything ask how they feel first, and only prompt the happy ones? Nothing here reads a blank as a no, least of all on the ones Apple attaches an expulsion clause to.

If we find that you have attempted to manipulate reviews, inflate your chart rankings with paid, incentivized, filtered, or fake feedback, or engage with third-party services to do so on your behalf, we will take steps to preserve the integrity of the App Store, which may include expelling you from the Apple Developer Program.

— App Review Guidelines — unnumbered preamble to section 3, Business

Unanswered: Incentivising

Is anything offered in exchange for a rating or review? Nothing here reads a blank as a no, least of all on the ones Apple attaches an expulsion clause to.

If we find that you have attempted to manipulate reviews, inflate your chart rankings with paid, incentivized, filtered, or fake feedback, or engage with third-party services to do so on your behalf, we will take steps to preserve the integrity of the App Store, which may include expelling you from the Apple Developer Program.

— App Review Guidelines — unnumbered preamble to section 3, Business

Unanswered: Forcing or blocking

Does anything in the app become unavailable until they rate? Nothing here reads a blank as a no, least of all on the ones Apple attaches an expulsion clause to.

Apps must not force users to rate the app, review the app, download other apps, or other store-related actions in order to access functionality, content, or use of the app.

— App Review Guidelines 3.2.2(x) — Business, Unacceptable

Unanswered: Custom review UI

Does your own interface collect the star rating or the review text? Nothing here reads a blank as a no, least of all on the ones Apple attaches an expulsion clause to.

Use the provided API to prompt users to review your app; this functionality allows customers to provide an App Store rating and review without the inconvenience of leaving your app, and we will disallow custom review prompts.

— App Review Guidelines 5.6.1 — App Store Reviews

Unanswered: Repeating on dismissal

Does a dismissed prompt come back sooner because it was dismissed? Nothing here reads a blank as a no, least of all on the ones Apple attaches an expulsion clause to.

Avoid pestering people. Repeated rating requests can be irritating, and may even negatively influence people’s opinion of your app. Consider allowing at least a week or two between requests, prompting again after people demonstrate additional engagement with your experience.

— Human Interface Guidelines — Ratings and reviews

Unanswered: Spacing between requests

Is there at least a week or two between any two requests to the same person? Nothing here reads a blank as a no, least of all on the ones Apple attaches an expulsion clause to.

Avoid pestering people. Repeated rating requests can be irritating, and may even negatively influence people’s opinion of your app. Consider allowing at least a week or two between requests, prompting again after people demonstrate additional engagement with your experience.

— Human Interface Guidelines — Ratings and reviews

Resetting the summary rating

Apple does document this, and it comes up whenever an app has recovered from a bad version. It is a per-territory summary rating and it resets only on a new version. Two things Apple says about it, quoted:

When you release a new version of your app or game, you can reset the summary of individual ratings you received since the last reset. Although resetting means that the ratings reflect the current version, it also tends to result in having fewer ratings overall, which can discourage some people from downloading your app.

— Human Interface Guidelines — Ratings and reviews

This summary rating is specific to each territory on the App Store and you can reset it when you release a new version of your app. However, we recommend using this feature sparingly. […] In addition, keep in mind that resetting your summary rating won’t reset your app’s written reviews.

— App Store — Ratings, reviews, and responses

No recommendation either way here — whether the trade is worth it depends on how many ratings you would be giving up and what the current ones say, and the worldwide sweep shows the per-storefront counts the decision actually turns on.

Every rule and number on this page is Apple’s, fetched and read on 2026-08-25 rather than recalled, from the Human Interface Guidelines, the StoreKit reference, Ratings, reviews, and responses and the App Review Guidelines (which state “Last Updated: June 8, 2026” on themselves). All 20 quotes are verbatim. Nothing was added to Apple’s rules, and where this page draws its own conclusion from them it says so in the sentence.

Apple’s guidance on spacing is a suggestion in its own words — “Consider allowing at least a week or two between requests”, so 7 to 14 days — and is carried as one, not turned into a schedule. Apple also notes that people can opt out of these prompts for every app they have installed, and that the API has no effect at all in TestFlight builds while always displaying in development, so what you see while testing is not what ships.

There is no claim anywhere on this page that ratings move search ranking. Apple documents no such factor. What Apple does state is that the summary rating is shown on the product page and in search results — that people see it, which is reason enough.

Your plan is stored in this browser only. Nothing is uploaded, and this page makes no network requests of any kind.

Where should your app ask for a rating?

Apple gives you three prompts per person per year and decides itself whether any of them actually appears. That makes the choice of moment the whole decision — there is no volume lever to pull, only the question of which three points in your app are worth spending on.

This is a worksheet for making that choice before you wire it up. You describe each moment; the page checks it against what Apple published, quotes the relevant sentence beside your answer, and flags the patterns that get developer accounts terminated.

It is the second half of the rating benchmark, which tells you whether you are short of ratings and then deliberately stops — where and when to ask is a product decision no cohort comparison can see.

How it works

  1. 1Write down each moment a prompt could fire: what the person has just done, and why that is a point of satisfaction rather than a convenient hook.
  2. 2Five questions open under each one, and every one exists because of a sentence Apple published — has something just gone well, is it gated on demonstrated engagement, could it fire during onboarding, does it interrupt a task, is it triggered by a button tap. Apple’s wording is shown when your answer runs into it.
  3. 3Answer the forbidden-pattern checklist for the plan as a whole: sentiment gating, incentivising, forcing, custom review UI, re-prompting on dismissal, and spacing. Four are guideline violations and two are design guidance; the page labels which is which.
  4. 4Every question is three-state. An untouched question stays untouched — nothing here reads a blank as a “no”, least of all on the ones Apple attaches an expulsion clause to.
  5. 5Copy the plan out as plain text for a ticket or a code review. Unanswered questions are printed as NOT ANSWERED rather than dropped.

What it cannot tell you

  • Apple never tells you whether the prompt was shown. The API returns nothing — no boolean, no completion handler, no callback — and Apple documents none, so no response rate, prompt-to-rating ratio or expected number of ratings exists here or anywhere else. Anyone quoting one for the system prompt is quoting something nobody can measure.
  • There is no score. Every question is a judgement about an app this page has never seen, and a passing mark where one item can end a developer account would be an invitation to stop reading.
  • It cannot see your app, your code or your analytics. It arranges your own answers and points at Apple’s wording; it never says an answer is wrong.
  • No claim that ratings move search ranking — Apple documents no such factor. What Apple does state is that the summary rating is shown on your product page and in search results.
  • No recommended number of moments and no benchmark for asking, because Apple publishes none.
  • What you see while testing is not what ships: Apple documents that the API always displays in development mode and has no effect at all in TestFlight builds.

Frequently asked questions

How often can an iOS app ask for a review?

StoreKit displays the prompt at most three times per person per app in a 365-day period, and enforces that itself. Calling the API more often is not a rejection — the extra calls simply show nothing, so wiring up more moments does not buy more prompts. It only changes which ones spend the year’s three displays.

Can I tell whether the review prompt was actually shown?

No. Both current APIs return nothing and Apple documents no callback — the request is made “if appropriate” and, in Apple’s words, “App Store policy governs the actual display of a rating and review request view.” That is why no response rate for the system prompt exists.

Is SKStoreReviewController still the right API?

No. Apple’s platform metadata marks it deprecated at iOS 18.0, macOS 15.0 and visionOS 2.0, pointing at AppStore.requestReview(in:); the page’s own deprecation summary points at RequestReviewAction instead. Use the SwiftUI requestReview environment value or AppStore.requestReview(in:). Note Apple’s own marketing page still names the old class, which is stale relative to the documentation.

Can I ask people how they feel first and only prompt the happy ones?

Don’t. Apple’s preamble to section 3 lists “filtered” feedback alongside paid, incentivized and fake, with expulsion from the Apple Developer Program named as a consequence, and 5.6.3 forbids manipulating any element of the App Store customer experience including reviews. Independently of the rules, it does not work as advertised: StoreKit decides whether the prompt appears, so screening only shrinks the pool your three annual displays can be spent on.

Can I put a “Rate us” button in my settings screen?

Not wired to the review API — Apple says explicitly not to call it in response to a button tap, because the call may present nothing and a button that does nothing reads as broken. Apple documents a different mechanism for that case: a persistent link to your App Store product page with action=write-review appended, which always opens something.

Should I reset my summary rating when I ship a new version?

Apple lets you, per territory, on a new version, and recommends using it sparingly — resetting makes the rating reflect the current version but tends to leave you with fewer ratings overall, which can discourage downloads. It also does not reset written reviews. Whether the trade is worth it depends on how many ratings you would give up, which is a number only you can see.

Do more ratings improve my App Store ranking?

Apple publishes no ranking factor for ratings, so nobody outside Apple can say. What is verifiable is that the summary rating appears on your product page and in search results, where people read it before deciding — which is reason enough without inventing a ranking claim.