Subscription Grace Periods, Billing Retry and Account Hold

Because a renewal charge failed, not because anyone decided anything — and both stores treat that as a temporary condition they will spend weeks reversing. Apple names the category: involuntary churn "occurs when users do not intend to leave your service but their subscription fails to renew, usually due to billing issues", and it is "not related to customer satisfaction".

The distinction matters because the two kinds of churn need opposite responses. A voluntary cancellation is a product problem, and no payment plumbing will change the subscriber's mind. An involuntary lapse is a plumbing problem, and the subscriber usually still wants the product. Treating the second as the first is how teams run win-back campaigns at people whose card simply expired.

Both stores build a recovery period into the lifecycle so you do not have to re-sell every declined card yourself. Google's subscription lifecycle documentation describes it plainly: "If there are payment issues with a subscription renewal, Google notifies the user and periodically attempts to renew the subscription for some time before the subscription expires. This recovery period can consist of a grace period followed by an account hold period."

Apple runs the same idea with different machinery. The designs diverge in one expensive way — what your app should do about entitlement while retries are happening — and that is where most recoverable revenue is thrown away. Across the 300+ apps we have managed since 2013, backends that get this wrong get it wrong in the same direction: they revoke access on the first failed renewal, on both platforms, because that is the simplest rule to write.

What follows is the fault tree: the states, their lengths, the notification announcing each, and what your server should do. If the offer itself is still unsettled, start with our subscription monetisation strategy guide.

Grace period first, where the user keeps access, then account hold, where Google's documentation says you should block it. The entitlement rule flips between the two states, and that flip is the most important thing to encode in your backend.

During the grace period, Google's guidance is explicit: "During a grace period, the user should still have access to their subscription entitlement." The subscription resource carries autoRenewEnabled = true, Google "dynamically extends the expiryTime value until the grace period has expired", and the state field reads SUBSCRIPTION_STATE_IN_GRACE_PERIOD.

Account hold reverses it: "after any grace period has ended, an account hold period begins. When a subscription enters account hold, you should block access to the subscription entitlement." The subscription is not gone — Google is still charging the card — but the user should not be receiving the product.

A third, quieter state exists. Google documents a silent grace period: "You can set a grace period of 0 days, but Play will wait a minimum of 1 day to ensure sufficient time for payment retries." During that 24-hour window the subscription remains ACTIVE. Even a team that deliberately disables grace gets no instant cut-off, and a backend assuming one will disagree with the store about who is entitled.

Two further mechanics change the funnel. A subscription "enters into account hold directly when the subscription resumes from a paused state with a failed form of payment", so a paused subscriber whose card has expired never passes through grace at all. And "when a subscription recovers from account hold, the renewal date resets", which shifts every downstream cohort date you were counting on. If you are on an older integration, check this state handling as part of the upgrade rather than after it — see the Play Billing Library 8 migration guide.

Google Play's default is a total recovery window derived from 60 days: account hold length is automatically calculated as 60 days minus whatever grace period you configured. That is the documented arithmetic, and it is the number to plan your dunning around.

The Play Console help page on understanding subscriptions states it plainly: "By default, all auto-renewing base plans have account hold enabled and the lengths are automatically calculated. The calculation will be 60 days minus any grace period duration." It adds a floor you cannot design around — "The total of account hold and grace period durations must total 30 days or more."

That 48-hour figure carries a condition, so keep them together. Google states: "Before a subscription enters into account hold, Google Play makes additional attempts to charge the payment method for up to 48 hours. The user retains subscription benefits during this period. After this retry period has elapsed, the subscription then enters into account hold, and the user should lose access to subscription benefits." It sits between grace and hold, not at the start of the sequence.

Google does not publish the retry cadence inside these windows — how many attempts, on which days, against which instruments — and we will not estimate it. The envelope and the entitlement rule at each stage are documented, which is enough to build correctly against.

Apple runs a billing retry period of up to 60 days with no account hold equivalent, and an optional Billing Grace Period that you must switch on in App Store Connect. If you never enabled it, your subscribers get no protected access at all when a card fails.

Apple's guidance on reducing involuntary subscriber churn sets the window: "If the customer's billing is invalid, the renewal fails and the user's subscription enters a billing retry state, where the App Store attempts to collect payment for up to 60 days." Recovery inside that window still costs you something — "If the user is recovered within the 60 days, the new billing date is established on the date of recovery and subsequent renewal dates are based on this new billing date."

Billing Grace Period protects your days of paid service, and its durations depend on the subscription period. Apple lists them as options, not a single default: "3 or 6 days for a weekly subscription" and "3, 16, or 28 days for monthly and longer subscriptions". Apple's auto-renewable subscriptions overview adds the scope choice — you can apply it "to all renewals (existing paid renewals and free offers transitioning to paid renewals) or only to existing paid renewals".

There is a trap in the timing. Apple states that "Billing Grace Period is applied at the time of a billing error when it's enabled for subscriptions in the app, and cannot be altered once assigned to a user." Turning it on after a subscriber has already hit a decline does nothing for them. Get it right before you need it; it is not a lever to pull during an incident.

The structural contrast with Play drives different backend logic on each platform. Play makes you revoke access during account hold and tells you when. Apple has no hold state — after grace expires the subscription expires while retries continue silently, and your only signal that the customer is still winnable is the retry flag. Whether you run that logic yourself or delegate it is the question behind StoreKit versus RevenueCat.

Real-time developer notifications on Play, App Store Server Notifications V2 on Apple — and on both platforms the recovery states have dedicated types you can key entitlement off directly. Polling on a schedule is not a substitute; the states change on the store's clock, not yours.

Google's real-time developer notifications reference assigns each state a numeric type. The ones that matter for involuntary churn are these:

• SUBSCRIPTION_IN_GRACE_PERIOD (6) — "A subscription has entered grace period (if enabled)." Keep entitlement on.
• SUBSCRIPTION_ON_HOLD (5) — "A subscription has entered account hold (if enabled)." Turn entitlement off.
• SUBSCRIPTION_RECOVERED (1) — "A subscription was recovered from account hold or resumed from pause." Note the two causes: this type does not tell you on its own which one happened.
• SUBSCRIPTION_CANCELED (3) — "A subscription was either voluntarily or involuntarily cancelled." Ambiguous by itself, and Google states you receive this type if the user does not fix their payment method before the end of the account hold period.
• SUBSCRIPTION_EXPIRED (13) — "A subscription has expired."
• SUBSCRIPTION_REVOKED (12) — "A subscription has been revoked from the user before the expiration time." Google's instruction here is unambiguous: revoke the user's entitlement immediately.

Apple's notificationType reference encodes the same journey as a type plus subtype pair, and the subtype is where the meaning lives. Apple maps them event by event: the subscription failing to renew and entering the billing retry period is DID_FAIL_TO_RENEW with no subtype; the same failure "with Billing Grace Period enabled" is DID_FAIL_TO_RENEW with subtype GRACE_PERIOD. Exiting the grace period while continuing in billing retry is GRACE_PERIOD_EXPIRED. A successful rescue is DID_RENEW with subtype BILLING_RECOVERY. Giving up is EXPIRED with subtype BILLING_RETRY — "the subscription expires because the billing retry period ends without recovering the subscription".

That last pair is the one to instrument first. EXPIRED with subtype VOLUNTARY means the customer chose to leave; EXPIRED with subtype BILLING_RETRY means the machinery ran for up to 60 days and lost. Two subtypes, two different post-mortems, and a churn dashboard that collapses them into one number cannot tell you which problem you have. If your funnel analytics stops at "expired", this is the split to add.

Follow the store's own instruction for each state rather than a rule of your own invention: on Play, access during grace and none during hold; on Apple, access for as long as the grace period you configured lasts. Every deviation costs you revenue or creates a support problem.

Purchase token behaviour on Play decides whether your database sees one subscriber or two. Recovery from account hold keeps the same token, and so does a restore — a user undoing a cancellation before expiry, announced as SUBSCRIPTION_RESTARTED. A resubscribe after expiry does not: "Google Play issues a brand new purchase token, and your backend receives an RTDN with type SUBSCRIPTION_PURCHASED." Keying a subscriber record on the token alone splits one person into two lifetime-value rows the moment they lapse and come back.

Use the store's own messaging surfaces first, because they prompt inside the payment account the user actually needs to edit. A generic "there was a problem with your payment" banner that links nowhere is the weakest version of this.

On Android, Play Billing exposes in-app messaging for exactly this case. Google's subscriptions documentation describes it as showing a message "when there is a payment issue or an outstanding opt-in price increase", appearing as a snackbar prompting the user to fix their payment "during grace period and account hold once per day". You call showInAppMessages() with the TRANSACTIONAL category, and Google recommends calling it whenever the user opens the app.

Handle the callback rather than ignoring it. NO_ACTION_NEEDED means the flow finished with nothing for you to do. SUBSCRIPTION_STATUS_UPDATED means the status changed — Google gives "a subscription is recovered from a suspended state" as an example — and the purchase token is returned with that response code for use with the Google Play Developer API. The user may have fixed their card two seconds ago, and your server can find out immediately instead of waiting for the next sync.

On iOS, Apple provides a system prompt and a deep link. Apple states that "Starting in iOS 16.4 and iPadOS 16.4, if a subscription doesn't successfully renew, a system-provided sheet appears in your app upon launch with a prompt that lets customers update the payment method for their Apple Account." Separately, your app "can deep link customers to the Manage Payments page on their account settings" — with a condition that must travel with it: "This URL is only supported for iOS and macOS."

Timing beats copy here. Both stores already email the user; your advantage is catching them as they open the app to use the thing they are about to lose — see in-app messaging versus push for when each channel is right.

Google states directly that specifying lengths less than the default values may reduce the number of subscriptions recovered from payment declines — so the trade is fewer recovered subscribers in exchange for less unpaid service. That is the whole decision, and the sentence appears in both the developer documentation and the Play Console help.

The temptation to shorten comes from a real cost. During a Play grace period you are serving a customer who has not paid, and on Apple, service delivered during a grace period that ends without recovery is unpaid — Apple says so: "Payment for the provided full service during the grace period would not be collected." For a content app with negligible marginal cost per user that is close to free. For an app where every active subscriber burns compute, bandwidth or a third-party API call, it is not.

Note what the floor does to the choice on Play: you can move the split between grace and hold freely, but the combined window cannot fall below 30 days, so "turn recovery off" is not an available setting on an auto-renewing base plan with account hold enabled. The decision is how much of the window the user spends with access, not whether the window exists.

We are not publishing a recovery rate for either configuration. No primary source publishes one, and our own portfolio numbers are not a benchmark anyone else should plan against. What is publishable is the direction, stated by the platform that owns the retries: shorter windows recover less.

Payment instrument changes this problem more than window length does. Where recurring card mandates are weak, the failure mode is a mandate that never authorised rather than a declined renewal — a different fault tree, covered in UPI AutoPay for app subscriptions. If declines cluster in one market, look at the payment rail before the grace period; sequencing both is what our monetisation practice exists to unpick.

Count the subscribers who entered a recovery state and came out the other side, using the store notifications as entry and exit events — not a figure modelled from your churn curve. Both platforms hand you the exact events, which makes this one of the few growth metrics that can be measured rather than estimated.

The pipeline on Play is: entries via SUBSCRIPTION_IN_GRACE_PERIOD and SUBSCRIPTION_ON_HOLD, successful exits via SUBSCRIPTION_RECOVERED, failed exits via SUBSCRIPTION_CANCELED at the end of account hold. On Apple: entries via DID_FAIL_TO_RENEW, with the GRACE_PERIOD subtype separating those who kept access from those who did not; successful exits via DID_RENEW with subtype BILLING_RECOVERY; failed exits via EXPIRED with subtype BILLING_RETRY.

Two adjustments stop the number from lying to you. First, the ambiguous types: SUBSCRIPTION_RECOVERED covers recovery from account hold and resumption from pause, and SUBSCRIPTION_CANCELED covers both voluntary and involuntary cancellation, so neither counts as a recovery metric without checking the prior state. Second, the date reset: the renewal date resets when a subscription recovers from account hold on Play, and Apple establishes a new billing date on the recovery date, so a recovered subscriber's future renewals no longer line up with their original cohort.

Then read it against everything else. Recovered subscribers are the cheapest you will ever add — no acquisition cost, no onboarding, no paywall to clear — so this changes the payback maths rather than sitting in its own report. Our guidance on cash payback on UA budgets and on ROAS and CAC assumes you know the difference between a subscriber you kept and one you re-bought.

Finally, review the configuration rather than setting it once. Grace and hold lengths, whether Billing Grace Period is enabled at all on iOS, whether in-app messaging is wired up, whether entitlement logic still matches the documented states after a billing library upgrade — in our portfolio these are the settings most likely to be inherited and never revisited.