Apple's Billing Grace Period Is Opt-In and Off by Default — Most iOS Subscriptions Have None

Ask a mobile team how their iOS app handles a failed subscription renewal and most will say some version of "Apple handles it" — Smart Retries for App Store subscriptions, basically, so nothing to configure. That's half right. Apple does retry a failed renewal automatically, for up to 60 days, with zero setup required. What most teams miss is the other half: whether the subscriber keeps using your app during those 60 days is a separate switch, it isn't flipped on by default, and Apple's own documentation says exactly what happens if you never touch it.

That gap exists because of a design decision Apple made on purpose, not an oversight. Billing Retry — the actual payment-collection engine — is unconditional. Billing Grace Period, which governs the subscriber's access during that retry window, is something you have to go into App Store Connect and turn on yourself. Skip it, and a subscriber whose card gets declined on renewal day loses access to your paid content that same day, even though Apple is still quietly trying to charge them for weeks afterward.

What actually happens without Billing Grace Period

Apple's own App Store Connect help documentation states the default outcome plainly: without enabling Billing Grace Period, "the subscriber's days of paid service pause until Apple is able to collect payment." Read that literally. It isn't a metaphor for a slightly degraded experience — paid access stops, immediately, on the first failed renewal attempt. The subscriber didn't cancel anything. They probably don't even know their card was declined yet. But your app now treats them as unsubscribed, and stays that way for as long as it takes Apple's background retries to succeed, or until the 60-day retry window runs out entirely.

Compare that with Billing Grace Period enabled: the subscriber keeps full paid access while Apple retries in the background, and — this is the part that matters for revenue, not just goodwill — if the payment recovers inside the grace window, there's no interruption to their days of paid service and no interruption to your recognized revenue. The subscription behaves, from the customer's side, as if nothing happened. From your side, you kept a paying customer through a card decline instead of losing and possibly never regaining them.

The row worth staring at is the first one, because it's the state every app ships in until someone changes it. Apple isn't being stingy with the retry itself — 60 days of automatic payment attempts, no API integration required, is genuinely generous compared to what you'd have to build by hand on web. What it withholds by default is the forgiveness on the customer-facing side, and that's the half of the equation that actually determines whether a subscriber sticks around long enough for one of those 60 days of retries to succeed.

The three settings you're actually choosing between

Turning on Billing Grace Period in App Store Connect (Apps → your app → Subscriptions → Billing Grace Period → Set Up Billing Grace Period) involves three decisions, and none of them are obvious defaults you can skip past:

• Duration — 3, 16, or 28 days. This is a menu, not a slider; there's no custom value between those three. The one built-in exception is weekly subscriptions, which are capped at 6 days of grace no matter which of the three options you pick, since a 7-day billing cycle doesn't leave much room before the next charge would be due regardless.
• Renewal scope — all renewals, or paid-to-paid only. "All renewals" covers both existing paid subscribers and free trials transitioning into their first paid charge. "Paid-to-paid only" excludes that free-to-paid conversion moment, which matters if you want grace period leniency for existing payers but not for a trial user's very first charge attempt.
• Environment — sandbox only, or production and sandbox. Worth testing in sandbox first regardless, but this is also where teams occasionally configure grace period correctly, verify it in sandbox, and then never flip the switch to include production — leaving the setting effectively inert for real subscribers.

None of this requires a new release. It's a dashboard configuration, and it applies to every future failed renewal the moment you save it — the same "highest-leverage 20 minutes" argument that applies to Google Play's account hold settings on Android. The mechanics differ — Google Play splits recovery into grace period plus a separate account hold state with its own duration formula, while Apple folds everything after grace directly into one 60-day retry window — but the underlying lesson is identical on both platforms: the recovery infrastructure already exists, and the gap is almost always that nobody went and turned it on.

Framed that way, even the shortest grace option isn't trivial — 3 days still covers a meaningful chunk of the retry window's early attempts, which is where most soft declines (insufficient funds clearing on a second attempt, a temporarily blocked card getting released) actually resolve. But the 28-day option covers nearly half the total retry runway with uninterrupted access, which is the difference between a subscriber who never notices anything went wrong and one who gets locked out, opens your app to a paywall, and has to decide whether re-engaging is worth the friction — the exact decision point where a recoverable payment failure quietly turns into a real cancellation.

Telling recoverable states apart from real churn

App Store Server Notifications V2 give you the signal to do this server-side, if your backend is actually parsing subtypes instead of just checking whether a subscription is currently active. A DID_FAIL_TO_RENEW notification with a GRACE_PERIOD subtype means the subscriber entered grace and is still recoverable. GRACE_PERIOD_EXPIRED means grace ran out without a successful charge, and the subscription has dropped into the ordinary billing retry state. A later DID_RENEW with a BILLING_RECOVERY subtype means a payment that failed came back — that's the save. Only EXPIRED with a BILLING_RETRY subtype, after the full 60 days has run out with nothing collected, is an actual, final cancellation.

This is the same modeling mistake we've flagged on the Android side: collapsing every one of those states into a single "canceled" bucket in your own database. A subscriber sitting in grace period isn't gone, and treating them as churned both inflates your involuntary churn number and, worse, can cause you to revoke access or stop messaging someone Apple is actively still trying to bill on your behalf. Your app should be checking StoreKit's renewal state directly rather than trusting a single boolean "is subscribed" flag, precisely because that flag can't distinguish a subscriber mid-recovery from one who's truly done.

The one message you can actually customize

Apple doesn't give you a customizable "update your card" email the way Stripe's dunning system does — there's no equivalent of writing your own second-failure or final-notice copy. But since iOS 16.4, there is one lever: a system-provided Billing Problem Message sheet appears automatically when a subscriber relaunches your app after a failed renewal, and the StoreKit Message API lets you defer that default sheet and show your own in-app messaging first, by checking for a message with .reason equal to .billingIssue before Apple's version takes over. It's a narrower lever than a full email sequence, but it's the difference between a subscriber's first signal being a generic system dialog and it being your own product explaining, in your own voice, exactly what happened and what to do about it.

What to actually check this week

• Open App Store Connect and confirm Billing Grace Period is on, not just configured in sandbox. Teams sometimes set this up once during initial development, verify it in the sandbox environment, and never extend it to production — leaving it dormant for every real subscriber.
• Match the duration to your billing cycle, the same logic that applies on Google Play. A weekly plan is capped at 6 days regardless of what you pick, so there's no decision to make there. For monthly and annual plans, 28 days gives the retry engine the most runway to succeed before a subscriber ever sees a lockout.
• Verify your backend parses App Store Server Notification subtypes, not just the top-level type. If your webhook handler branches only on DID_FAIL_TO_RENEW without checking for the GRACE_PERIOD subtype, you can't tell a recoverable grace-period entry from a subscriber who's already dropped into unforgiving billing retry.
• Use StoreKit's renewal state in-app, not a cached "is subscribed" boolean. A subscriber can be in grace period, fully entitled, and still show as inactive if your entitlement check was written before this distinction existed.

None of this touches the part of iOS billing this site usually covers — a subscriber who genuinely wants out still needs a real off-ramp, and Apple's platform, as we've written about with Stripe's iOS BillingSDK, still doesn't give you a cancel-moment intercept the way a web checkout does. Billing Grace Period solves a narrower, earlier problem: keeping subscribers who never decided to leave from getting treated as if they had. If your app sells through the App Store and nobody on the team can say with certainty whether Billing Grace Period is turned on, that's worth confirming before anything else on this list — it's a setting, not a rebuild, and per Apple's own documentation the default behavior without it is an immediate access pause on every single card decline. Once that's fixed, run the involuntary share of your iOS cancellations through our churn calculator against a 15–20% recovery lift to see roughly what it's worth in retained subscribers before you touch anything else on your mobile billing stack.

Frequently asked questions

Stop losing subscribers today

One script tag. One function call. A live cancellation flow in under 10 minutes.