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.
|App Store||Optional||6 days (weekly products)|
16 days (monthly and up)
|Amazon||❌ Not supported||N/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
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.
Customers who enter into a grace period will have events added to their Customer History.
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.
Updated 5 months ago