App subscriptions: billing retry and grace periods explained
Short answer: When a subscriber's renewal payment fails in your iOS or Android app, both stores keep trying to collect it for a while instead of cancelling straight away. A grace period lets the person keep using what they paid for during the first part of that recovery; after it, access should pause until payment succeeds. Turn the grace period on, make your app read the subscription state correctly, and show a gentle "update your payment method" prompt that links straight to the right settings page.
Why this matters for a small subscription app
Some cancellations aren't cancellations at all. A card expires, a bank declines a charge, or a prepaid balance runs low. The subscriber still wants your app; their payment just failed. Apple calls this involuntary churn, and both stores have built-in recovery for it. Your job is to make sure your app behaves sensibly while the store does its work, so people aren't locked out abruptly or, the opposite, given free access forever.
How Apple handles it
Apple's StoreKit documentation describes what happens when a renewal fails. The subscription enters a billing retry state, and the App Store attempts to collect payment for up to 60 days. If the subscriber is recovered within those 60 days, the new billing date is set from the date of recovery.
On top of that, you can enable Billing Grace Period in App Store Connect. During the grace period the subscriber keeps access while Apple retries, so their paid service isn't interrupted if recovery succeeds. Apple lists the available durations:
- 3 or 6 days for weekly subscriptions
- 3, 16 or 28 days for monthly and longer subscriptions
After the grace period ends, the subscription is still in billing retry, but access should stop until payment goes through.
Apple also gives you a URL to send people to their payment settings: https://apps.apple.com/account/billing. Its guidance is that your app should be ready to react immediately when billing information is updated.
How Google Play handles it
Google Play's subscription lifecycle documentation describes a recovery period made of a grace period followed by account hold.
- Grace period. By default, all auto-renewing base plans have a grace period enabled. You can change its length or switch it off in the Play Console, though Google notes a shorter period may mean fewer subscriptions are recovered. During the grace period the user should keep access. The subscription state reads
SUBSCRIPTION_STATE_IN_GRACE_PERIOD, and if the subscription recovers, the renewal date doesn't reset. - Account hold. If payment still hasn't succeeded when the grace period ends, the subscription moves to account hold, and Google says the user should lose access to subscription benefits. The state reads
SUBSCRIPTION_STATE_ON_HOLDand the expiry time is in the past. When it recovers from account hold, the renewal date resets.
Google also points out that the client method queryPurchasesAsync() continues to return purchases in the grace period, so an app relying only on that call can't tell a healthy subscription from one in trouble. Your back end, using the Play Developer API, is the place to read the real state.
What your app should do in each state
A simple table makes the rules clear for your team.
| State | Access | What to show |
|---|---|---|
| Active | Full | Nothing special |
| Grace period | Full | A banner asking them to update payment |
| Billing retry after grace (Apple) or account hold (Google) | Paused | A screen explaining access is paused and how to fix it |
| Recovered | Full | A short "you're all set" confirmation |
| Expired | None | Your normal resubscribe screen |
The key is that your app decides access from the state, not from whether a purchase object exists on the device.
Writing the prompt
People react badly to alarming payment messages. Some ideas that keep it calm and useful:
- Say what happened in plain words. "We couldn't renew your subscription. Your payment method may have expired."
- Say what happens next. During grace: "You still have full access while we sort it out." During hold: "Your access is paused until payment goes through."
- Give one button. On iOS, open Apple's billing URL. On Android, send them to the subscriptions area of the Play Store, which Google documents for managing subscriptions.
- Don't nag on every screen. One banner on the home screen, plus a reminder when they open a premium feature, is usually enough.
- Don't ask for card details yourself. Store subscriptions are billed by Apple or Google; your app can't take the payment.
Server-side tracking
Your server should learn about these changes as they happen rather than waiting for the user to open the app. Apple sends server notifications, including one of type DID_FAIL_TO_RENEW when a renewal fails, and Google sends real-time developer notifications for subscription changes. Using those to update your records means the right banner is waiting the next time the app opens, and any web version of your product can apply the same access rules.
Common mistakes
- Cutting access the moment a payment fails. Annoys people who would have recovered within days.
- Leaving access on indefinitely. If your app only checks "was this ever purchased", people in account hold keep premium features.
- Forgetting other platforms. If subscribers also log in on the web, apply the same state there.
- Not testing it. Both stores provide test tools for subscription scenarios. Test grace, hold and recovery before launch, not after the first complaint.
A worked example
A hypothetical Denver fitness coaching app sells monthly subscriptions on both stores. Its app only checked for a purchase on the device, so people in account hold kept full access, while iOS users whose renewals failed were locked out at once. The developer enabled a 16-day Billing Grace Period on iOS, kept Google's default grace period, and moved access decisions to the server based on store state. Subscribers in grace now see a single banner with a button to their payment settings, and those in hold or retry see a paused-access screen.
FAQ
Do I lose revenue by giving access during grace?
If the payment is recovered, the store bills it as normal. If it never recovers, you've given a few extra days of access, which is the trade-off the grace period makes.
Can I offer a discount to win back people in account hold?
You can design win-back offers, but first make sure they're not shown to people who simply need to update a card.
Do free trials go through grace periods?
Renewals after a trial can fail like any other renewal. Check each store's documentation for how your specific offer is treated.
Will users get emails from Apple or Google about failed payments?
Both stores notify users about payment issues, but your own in-app message is what people see when they open your app.
If your subscription app treats failed payments too harshly or too loosely, tell us how it checks access today.