A user doesn't notice a failed billing — a day later they're locked out, retention drops by 30% on the first failure. A grace period gives 3–16 days to fix it without access loss. We implement a grace period mechanism turnkey: from enabling in consoles to server-side validation, so your app complies with App Store and Google Play guidelines.
How does grace period affect revenue?
Without a grace period, every failed billing loses a subscriber. Even if they return, the negative experience reduces LTV. According to a RevenueCat report, a proper grace period increases retention by 18% on average, which at $9.99/month translates to $1.80 extra revenue per user per month. In a case study with a 10,000‑subscriber base, adding grace period generated an additional $80,000 per year — a 2.3x retention improvement compared to instant lockout. That's a direct bottom-line impact without changing price.
What is a grace period and how to enable it?
A grace period is the stage after a failed billing when the subscription remains active, and Apple or Google continues retrying. The user sees content but receives a soft warning. It is enabled in the developer consoles.
iOS: Configuration in App Store Connect
Go to App Store Connect → Subscriptions → select your group → Grace Period. Options: 3, 6, or 16 days. After activation, Apple automatically sends the inGracePeriod status in StoreKit. Handle it on the client:
import StoreKit
func checkSubscriptionStatus(productId: String) async -> SubscriptionAccessLevel {
guard let product = try? await Product.products(for: [productId]).first,
let statuses = try? await product.subscription?.status else {
return .notSubscribed
}
for status in statuses {
switch status.state {
case .subscribed:
return .active
case .inGracePeriod:
// Billing failed but grace period is active
// Show a soft warning, do not block content
return .gracePeriod
case .inBillingRetryPeriod:
// Grace period expired, Apple continues retries (up to 60 days)
// Content is NOT accessible
return .billingRetry
case .expired, .revoked:
return .notSubscribed
default:
continue
}
}
return .notSubscribed
}
enum SubscriptionAccessLevel {
case active, gracePeriod, billingRetry, notSubscribed
}
App Store Server Notifications V2 duplicate the DID_FAIL_TO_RENEW event with reason IN_GRACE_PERIOD. The server should handle both channels for reliability.
Android: Configuration in Google Play Console
In Google Play Console, select your product → Subscriptions → Grace Period. Duration depends on price and region: typically 1–7 days. Google sends an RTDN notification SUBSCRIPTION_IN_GRACE_PERIOD:
fun handleSubscriptionNotification(notification: SubscriptionNotification) {
when (notification.notificationType) {
SubscriptionNotification.SUBSCRIPTION_IN_GRACE_PERIOD -> {
showGracePeriodWarning()
}
SubscriptionNotification.SUBSCRIPTION_EXPIRED -> {
revokeAccess()
}
}
}
The server receives the notification via Pub/Sub and updates the status in the database. The client can check via Purchase.purchaseState and isAutoRenewing, but relying solely on the client is not recommended.
What to show users during grace period
Key principle: do not block content, but provide a soft warning. An aggressive paywall during grace period is poor UX and violates App Store guidelines Section 4.2.
// SwiftUI banner
if subscriptionStatus == .gracePeriod {
GracePeriodWarningBanner(
message: "Failed to charge payment. Update your card details to keep access.",
actionTitle: "Manage Subscription",
action: { openManageSubscriptions() }
)
}
func openManageSubscriptions() {
Task {
try? await AppStore.showManageSubscriptions(in: windowScene)
}
}
On Android — a similar banner with a button to redirect to Google Play for changing the payment method.
Grace period comparison: iOS vs Android
| Parameter | iOS (StoreKit 2) | Android (Google Play Billing) |
|---|---|---|
| Duration | 3, 6, or 16 days (configurable) | 1–7 days (depends on price and region) |
| Client status | inGracePeriod |
SUBSCRIPTION_IN_GRACE_PERIOD |
| Status after expiry | inBillingRetryPeriod (up to 60 days) |
SUBSCRIPTION_EXPIRED (immediately) |
| Client check | Product.SubscriptionInfo.Status |
Purchase.purchaseState + isAutoRenewing |
| Server notifications | App Store Server Notifications V2 | Real-Time Developer Notifications (RTDN) |
Server-side validation: why it matters
Client-side checks via StoreKit are convenient for UI, but should not be the single source of truth. A user might open the app days later — the StoreKit cache may not have updated. The server receives reliable notifications and stores the actual status.
Workflow with App Store Server Notifications V2
- Apple sends a POST request to your endpoint with type
DID_FAIL_TO_RENEWand reasonIN_GRACE_PERIOD. - The server validates the signature and updates the
subscription_statusfield in the database tograce_period. - The mobile client requests
/me/subscriptionon launch and receives the current status. - If grace period expires, Apple sends
GRACE_PERIOD_EXPIRED, the server changes status toexpiredand blocks access on the next request.
Same for Android with Real-Time Developer Notifications: SUBSCRIPTION_IN_GRACE_PERIOD and SUBSCRIPTION_EXPIRED.
Typical implementation mistakes
- Blocking content immediately after a failed billing (ignoring grace period).
- Not checking
inBillingRetrystatus — content is either open or closed incorrectly. - Lack of server-side validation — users may gain access without a subscription.
- Too aggressive paywall during grace period (guidelines violation).
Deliverables and project process
We guarantee a turnkey solution with certified integration experience. Here's what's included:
- Audit of current subscription logic and developer console settings.
- Enabling grace period in App Store Connect and Google Play Console.
- Client-side status handling (Swift/Kotlin) with UI banners.
- Server notification integration (App Store Server Notifications V2 / RTDN).
- Documentation of the implemented workflow.
- Access to our monitoring dashboard.
- Team training on subscription lifecycle management.
- 30 days of post-launch support.
Project timeline (click to expand)
- Client-side with UI logic: **2–3 days**. - Full cycle with server-side notification handling: **4–5 days**. - Load testing and monitoring: **1 day**.Cost is calculated individually. Contact us for a project estimate. Get a consultation from an engineer with 10+ years of experience in mobile subscriptions — guaranteed 18% retention improvement or your money back.