A grace period keeps the app working while the card fails, and on the App Store it is off until you turn it on.
A subscription billing grace period is the stretch of time after a renewal payment is declined in which the subscriber still gets your paid content, while the store keeps trying the card. Apple calls it Billing Grace Period, offers a menu of 3, 16 or 28 days, and applies your choice to every subscription product in the app. Google calls it a grace period, sets it on each base plan, and follows it with an account hold during which the subscriber is supposed to lose access. Every figure below comes from Apple's and Google's own documentation, read on 21 October 2026. Apple's setting sits in the Subscriptions section of App Store Connect, alongside the price. If you have not settled that yet, start with app store pricing tiers.
What follows is the exact durations each store documents, who keeps access and who does not, whether any of it is on by default, and the number Google does not publish anywhere we could find it. Then the detail that costs money: a grace period you serve and never get paid for.
Start hereThe short version
Apple gives you three numbers. Google gives you a blank field.
On the App Store you turn Billing Grace Period on for the whole app, choose 3, 16 or 28 days, and that is the end of the decision. Weekly products quietly top out at 6 days. Monthly products with a 12 month commitment get nothing at all. The subscriber keeps full access throughout, and if the card goes through before the grace period ends, your renewal date and your revenue carry on as though nothing happened.
On Google Play the grace period is a field on each auto-renewing base plan, and the length is yours to type. The pages we read describe what the grace period does and what comes after it, but print no menu of durations and no default. They are specific about the second half of the recovery window instead. Account hold is enabled for every auto-renewing base plan, its length is 60 days minus whatever grace period you set, and grace plus hold has to come to 30 days or more.
What is a subscription billing grace period?
A card expires. A bank declines a renewal. The customer has done nothing wrong and does not know anything has happened. A billing grace period is the window in which you keep serving them while the store sorts the payment out. App Store Connect Help describes it as letting subscribers whose auto-renewal failed due to a payment issue continue accessing your app's paid content for a period of time, while Apple continues to attempt to collect payment. Without it, Apple says the subscriber's days of paid service pause until Apple is able to collect.
The grace period is not the whole recovery window. Apple's StoreKit article on reducing involuntary subscriber churn, read on 21 October 2026, says a billing issue puts the subscription into a billing retry state where the App Store attempts to collect payment for up to 60 days. The grace period sits inside those 60 days. A subscriber recovered during the grace period keeps their existing renewal date. A subscriber recovered after the grace period has expired but still inside the 60 days renews on the day of recovery and starts a new billing cycle.
That distinction has a price attached, and it is the reason to think about the length rather than picking the biggest number. Apple states that payment for the full service you provided during the grace period would not be collected if the recovery happens after the grace period ends. You served the content. Nobody paid for those days. On a yearly product that is a rounding error. On a weekly product sold for very little it is most of the margin, and Apple's 6 day cap on weekly subscriptions is the only thing keeping that exposure small.
One more thing it is useful to separate out. A grace period covers a payment that failed. A refund covers a customer who asked for their money back. The two have different consequences and different paperwork. Someone whose renewal failed still holds a valid entitlement for the length of the grace period, which is why the restoring purchases requirement has to keep working for them after a reinstall.
What durations do Apple and Google document?
Apple publishes three. From the Billing Grace Period section in App Store Connect you select a period of 3, 16 or 28 days, and it applies across all subscription products in your app. Apple says configurability is not available for individual subscription products, so one app gets one answer. If your app sells weekly subscriptions, Apple's own note says the actual grace period will only be 6 days even when you have selected 16 or 28, to keep it from running longer than the subscription. The table on that page reads 3, 6, 6 for weekly subscriptions and 3, 16, 28 for monthly and yearly ones.
Google publishes none, and that is worth stating carefully because plenty of write-ups quote a list of day options as though it came from Google. On 21 October 2026 we read three first-party pages: Play Console Help on understanding subscriptions, Play Console Help on creating and managing subscriptions, and the About subscriptions page in the Play Billing documentation on the Android Developers site. All three treat the grace period as a length you choose on each auto-renewing base plan. The Play Console Help field description says only to select the maximum duration users will retain subscription entitlements while a declined renewal payment remains unresolved. No menu of numbers appears on any of the three, and neither does a default length.
What Google does publish is the arithmetic on the other side of it. Account hold is enabled by default on every auto-renewing base plan and on installment plans, and its length is calculated for you as 60 days minus any grace period duration. You can shorten it or switch it off in Play Console. The floor is that account hold and grace period together must total 30 days or more. Google adds that choosing lengths below the defaults may reduce the number of subscriptions recovered from payment declines. There is also a rule for subscriptions with add-ons: the recovery period follows the active item with the shortest grace period, and where several items tie on grace, the longest of their account hold periods applies.
Pick the number
What each subscriber actually gets
App Store Connect gives you one menu with three numbers, and it applies to every subscription product in the app. The row that catches people is the weekly one.
A weekly subscription
Grace period: 6 days
Capped so the grace period is never longer than the subscription itself.
A monthly subscription
Grace period: 16 days
Gets the number you picked.
A yearly subscription
Grace period: 16 days
Same row as monthly in Apple's own table.
A monthly subscription with a 12 month commitment
Grace period: Not available
Apple states Billing Grace Period does not apply to this one.
Figures from App Store Connect Help, read 21 October 2026. Google publishes no matching menu of numbers, which the next section covers.
Google, Play Console Help, understanding subscriptions, read 21 October 2026
Is a grace period on by default?
On the App Store it is not. The help page is titled Enable Billing Grace Period, and the path is to open Apps, select your app, click Subscriptions in the sidebar, then click Set Up Billing Grace Period in the Billing Grace Period section. You choose the duration, then two things people do not expect. First, which renewals it covers: All Renewals, which includes free introductory offers and free subscription offers moving to paid, or Only Paid to Paid Renewals, which skips anyone currently in a free period. Second, which environments it is live in: Only Sandbox Environment, or Production and Sandbox Environment. Then you click Confirm. Doing any of it needs the Account Holder, an Admin or an App Manager.
Apple's suggested order is sandbox first. Turn it on in sandbox, validate that your client and server handle subscribers entering and leaving the grace period, then edit the configuration to cover production. Two timing notes come with that. Product metadata changes can take up to an hour to show up in the sandbox environment. And edits to a live Billing Grace Period configuration can take up to 24 hours to take effect and apply only to upcoming renewals, because anyone already in a grace period stays entitled to service for the rest of it. Apple's churn article puts the same rule more sharply: the grace period is applied at the moment of the billing error and cannot be altered once it has been assigned to a user.
On Google Play the honest answer is that the two Google pages do not say the same thing. Play Console Help says that by default this recovery period consists of a grace period, followed by an account hold period. The About subscriptions page on the Android Developers site says the subscription enters a grace period if one is configured, which is a different claim. Both agree about account hold, which is explicitly on by default with a calculated length. So open the base plan and read the value rather than trusting either sentence. On the Android Developers wording, a base plan with no grace period configured sends a declined renewal straight into account hold, which is the stage where access is meant to be gone.
Account hold is the piece with no App Store equivalent, and it is the reason the two stores feel different to a subscriber whose card has failed. Google says the user should not have subscription entitlement during account hold, and that if the hold ends with the payment issue unresolved the subscription is automatically expired. Apple has no second stage: a failed renewal with no grace period configured just pauses the days of paid service while the retries continue. Neither of those is a refund, and if you have reached this page because money is going back out of the door, start with refund handling ios android instead.
Google, Play Console Help, declined payments, grace periods and account hold, read 21 October 2026
What do you have to build for it to work?
Turning the setting on does not unlock your app. App Store Connect Help is direct about it: your app still needs to perform purchase validation and account for the subscriber's renewal status to identify whether a subscription is in a Billing Grace Period. If your paywall checks nothing but an expiry date, every subscriber in a grace period hits the paywall, which is the exact outcome the feature exists to prevent.
The fields to read have two spellings, and that trips up a code search. StoreKit exposes isInBillingRetry on the renewal information, a Boolean for whether Apple is still attempting to renew an expired subscription, together with gracePeriodExpirationDate, which holds a date while the subscription is in a grace period. Apple's App Store Server API calls the same value gracePeriodExpiresDate and documents it as the time when the Billing Grace Period for subscription renewals expires. Grep for one spelling and you will conclude your server is not getting the other.
On Google Play the instruction runs in both directions. During the grace period you should make sure the user still has access to the subscription entitlements. During account hold you should make sure the user does not. That is two code paths, and the second one is the one nobody tests. Google also offers in-app messaging for this: the Android Developers About subscriptions page says that when in-app messaging is enabled, the payment issue message is shown once per day during grace period and account hold, so the person can fix the card without leaving the app.
Test it before you need it. Apple's own workflow asks you to turn Billing Grace Period on in sandbox only, drive a subscriber into and out of the grace period there, and move it to production afterwards. Expect the sandbox clock to be fast and expect the metadata to lag by up to an hour. The failure you are hunting for is silent: an app that looks fine to everyone paying and locks out the handful of people whose bank declined one charge.
Apple, App Store Connect Help, workflow for enabling Billing Grace Period, read 21 October 2026
The App Store and Google Play, side by side
| The question | App Store, Billing Grace Period | Google Play, grace period | Same answer on both |
|---|---|---|---|
| Where you set it | App Store Connect, app sidebar, Subscriptions, Billing Grace Period section | Play Console, on each auto-renewing base plan | No |
| How far one setting reaches | Every subscription product in the app, no per-product choice | One base plan at a time | No |
| Durations printed in the documentation | 3, 16 or 28 days, and 6 days for weekly | None on the three pages read on 21 October 2026 | No |
| Subscriber keeps access during it | Yes | Yes | Yes |
| On by default | No, you turn it on per app | Account hold is. The two Google pages disagree about the grace period | No |
| A period with access removed comes after it | No, the retry simply pauses days of paid service | Yes, account hold, then automatic expiry | No |
| Your own code has to read the renewal state | Yes | Yes | Yes |
Where this lands if a builder generated your app
The grace period setting lives in App Store Connect and Play Console, so it is yours either way. No builder can tick it for you, because both stores hang it off the account that owns the subscription products. What a builder can affect is the other half, the code that reads the renewal state and decides whether to show the paywall.
Newly is an AI app builder. You describe an app in plain English and it writes a real React Native and Expo project that you own, with two-way GitHub sync, so the entitlement check is ordinary TypeScript you can open and read. It uploads iOS builds to TestFlight and publishes to Google Play internal testing, and it builds a standalone Android APK. It does not submit to the App Store for you, because Apple requires the owner of the content to submit. It costs $25 a month and there is no free tier.
The practical advice for a generated app is the same as for a hand-written one. Ask for a paywall that reads the renewal state rather than an expiry date, and keep a sandbox test account you can push into billing retry whenever you touch that code. Neither store charges you for the grace period itself; what you pay for is the developer programme and the commission, which is covered in the cost to publish an app.
Questions people ask about subscription grace periods
It is the window after a renewal payment is declined in which the subscriber keeps full access to your paid content while the store carries on trying to collect. Apple's words are that Billing Grace Period lets subscribers whose auto-renewal failed due to a payment issue continue accessing your app's paid content for a period of time while Apple continues to attempt to collect payment. Google's words are that during the grace period the user retains subscription entitlement. The point of it is that a dead card should not look to the customer like a cancelled account.
Set the number, then make the paywall read it
Pick a grace period, write it down, and spend an afternoon in sandbox driving one test account through a declined renewal. It is the cheapest way to find out whether your paywall believes the renewal state or just the expiry date.
Start building