Terminal
Terminal/Skill
Explains how failed Android renewals appear in RevenueCat during grace period and account hold, and when to prompt users to fix payment.
By RevenueCat
Works with
npx skills add revenuecat/ai-toolkit --skill rc-payment-recoveryFailed renewals on Google Play move a subscription through two states: grace period (user keeps access while Google retries the card) and account hold (access revoked until the user fixes the payment method). With RevenueCat, both states land in CustomerInfo automatically, and Google's in app message shows by default.
Three things happen when a renewal fails:
| State | Access | How RevenueCat surfaces it | User sees |
|---|---|---|---|
| Grace period | Retained | entitlement.isActive == true and billingIssueDetectedAt != null | Google in app snackbar by default |
| Account hold | Revoked | entitlement.isActive == false and billingIssueDetectedAt != null | Google in app snackbar by default |
| Recovered | Retained | billingIssueDetectedAt == null | Nothing |
Two signals matter in the SDK:
EntitlementInfo.billingIssueDetectedAt is non null from the moment Google reports a billing problem until the user resolves it.EntitlementInfo.isActive tells you whether they still have access.On the backend, a BILLING_ISSUE webhook fires once per transition. You do not decode RTDNs.
Before you write app code, decide what you actually need. Most apps need none.
Ask:
showInAppMessagesIfNeeded on BillingClient connect.billingIssueDetectedAt from CustomerInfo and branch on isActive.showInAppMessagesIfNeeded(activity) yourself.BILLING_ISSUE webhook. No app code required.If you only want the default behavior, stop here.
Leave automatic in app messages on. This is the default:
PurchasesConfiguration.Builder(context, apiKey)
.showInAppMessagesAutomatically(true)
.build()
Disable the automatic call and show the message from your chosen activity:
PurchasesConfiguration.Builder(context, apiKey)
.showInAppMessagesAutomatically(false)
.build()
Purchases.sharedInstance.showInAppMessagesIfNeeded(activity)
Read the entitlement and branch on both flags:
val entitlement = customerInfo.entitlements["pro_access"]
when {
entitlement == null || !entitlement.isActive ->
showSubscribeScreen()
entitlement.billingIssueDetectedAt != null && entitlement.isActive ->
showGracePeriodWarning()
entitlement.billingIssueDetectedAt != null && !entitlement.isActive ->
showAccountHoldScreen()
else ->
showPremiumContent()
}
CustomerInfo.managementURL points to the Google Play subscription page:
customerInfo.managementURL?.let { url ->
startActivity(Intent(Intent.ACTION_VIEW, url))
}
Test each transition:
entitlement.billingIssueDetectedAt becomes non null and isActive stays true.isActive flips to false while billingIssueDetectedAt remains non null.billingIssueDetectedAt returns to null.BILLING_ISSUE webhook fires on the first transition.