Billing Issues & Grace Periods

What happens when a user encounters a billing issue

If a customer is unable to complete their purchase due to an invalid or expired payment method, supported stores offer an optional grace period. Grace periods allow the customer to retain access to their subscription purchase for a short period of time while the store attempts to renew the subscription. This prevents disruption for paid features, and can improve the user experience for your app.

Grace Periods are optional and customizable on certain platforms.

StoreRequired?Duration
App StoreOptional6 days (weekly products)
16 days (monthly and up)
Google PlayOptionalCustomizable
StripeOptionalCustomizable
Amazon❌ Not supportedN/A

Encountering Billing Issues

As mentioned, billing issues occur when a user is unable to complete a subscription purchase due to an invalid or expired payment method. When this occurs, RevenueCat sends a BILLING_ISSUE event to webhooks, integrations, and the customer history page.

RevenueCat will only send one billing issue event -- additional payment failures won't trigger additional billing issue events, unless a renewal is successful between payment failures or the subscription ends and is restarted.

Entering a Grace Period

When a subscription enters a grace period, RevenueCat detects the change automatically. Users will retain access to their subscriptions, but we'll immediately send events indicating the subscription has been cancelled. These subscriptions are considered cancelled because they are now past due, but will not be considered expired until the end of their grace period. During this time, a subscription may convert to paid through additional billing attempts from the store or by the customer updating their billing information.

API, Events, and Webhooks

To detect grace periods in webhook events, watch for the value of grace_period_expiration_at_ms. This property is only valid for BILLING_ISSUE events.

To detect grace periods in the GET /subscriber endpoint, watch for the value of grace_period_expires_date on a subscription object and compare it to the current date. This property will be null if the subscription is not in a grace period.

Once a user corrects their payment method, RevenueCat will send a renewal event. This will reset the grace_period_expires_date property to null in the GET /subscriber endpoint.

Dashboard

Customers who enter into a grace period will have events added to their Customer History.

12441244

Additionally, subscriptions that are currently in a grace period will still be considered "active," since the customer retains access to their entitlement throughout their grace period. Distinct customers who are currently in a grace period can be counted through Customer Lists using the "Billing Issue Trial" and "Billing Issue" statuses.