Terminal
Terminal/Skill
Guide to handling failed Google Play subscription renewals, covering grace period, account hold, RTDN signals, and in app recovery messages.
By RevenueCat
Works with
npx skills add revenuecat/play-billing-skills --skill payment-recoveryGoogle Play does not cancel a subscription the moment a renewal charge fails. It runs a two stage recovery process: grace period (user keeps access while Google retries) then account hold (access revoked while Google keeps retrying). Your job is to react to the right RTDNs, toggle entitlements at the right moments, and prompt the user to fix payment without forcing them to leave your app.
Map the stages, the RTDN for each transition, and the entitlement you should hold.
| Stage | Entry RTDN | Duration | User access | SubscriptionPurchaseV2 state |
|---|---|---|---|---|
| Silent grace period | none (always applies) | ~1 day | Active | SUBSCRIPTION_STATE_ACTIVE |
| Configured grace period | SUBSCRIPTION_IN_GRACE_PERIOD | 0 to 30 days (per base plan) | Keep full access | SUBSCRIPTION_STATE_IN_GRACE_PERIOD |
| Account hold | SUBSCRIPTION_ON_HOLD | 0 to 30 days | Revoke | SUBSCRIPTION_STATE_ON_HOLD |
| Recovered | SUBSCRIPTION_RECOVERED | n/a | Restore immediately | SUBSCRIPTION_STATE_ACTIVE |
| Terminal failure | SUBSCRIPTION_CANCELED or SUBSCRIPTION_EXPIRED | n/a | Gone | canceled/expired |
Key facts to internalize before writing any code:
Purchase objects look identical in grace period and in a healthy renewal: isAutoRenewing = true, purchaseState == PURCHASED. You cannot detect grace period from queryPurchasesAsync(). Source of truth is the server side RTDN plus SubscriptionPurchaseV2.subscriptionState.expiryTime points to the end of the grace window, not the original renewal date.expiryTime from SubscriptionPurchaseV2; cached pre failure dates will be wrong.Decide these rules before you touch code. The rest of the skill is mechanical once this is set.
| Stage | Entitlement | Primary UI | Secondary channels | Urgency |
|---|---|---|---|---|
| Silent grace period | Keep | none (you do not see the RTDN) | none | n/a |
| Grace period | Keep | Dismissible banner on main screen | Push on day 0, email by day 3, optional showInAppMessages(TRANSACTIONAL) at natural launch points | Soft, informational |
| Account hold | Revoke | Full screen account hold screen with single CTA | Push on transition, email midway through hold | High, blocking |
| Recovered | Restore | Optional toast or inline confirmation | Optional confirmation email | n/a |
| Canceled after hold | Gone | Resubscribe screen | Final email with resubscribe link | n/a |
SUBSCRIPTION_IN_GRACE_PERIOD plus banner in app.SUBSCRIPTION_RECOVERED: clear both flags, restore entitlement, persist the new expiryTime, optional confirmation message.SUBSCRIPTION_ON_HOLD. Do not wait for the user to open the app.Purchase.isAutoRenewing, as the source of truth for recovery state.SUBSCRIPTION_RECOVERED, overwrite the cached renewal date with the new expiryTime.SUBSCRIPTION_ON_HOLD and SUBSCRIPTION_CANCELED volume after the change.For each RTDN, look up the purchase token, fetch SubscriptionPurchaseV2 from the Google Play Developer API, confirm the state, then flip flags.
SUBSCRIPTION_IN_GRACE_PERIOD:
subscriptionState == SUBSCRIPTION_STATE_IN_GRACE_PERIOD.gracePeriod = true on the user record. Keep entitlement active.SUBSCRIPTION_ON_HOLD:
subscriptionState == SUBSCRIPTION_STATE_ON_HOLD.onHold = true. Revoke the entitlement now.SUBSCRIPTION_RECOVERED:
// Server side handler
fun handleSubscriptionRecovered(token: String, pkg: String) {
val sub = playApi.getSubscriptionV2(pkg, token)
if (sub.subscriptionState != "SUBSCRIPTION_STATE_ACTIVE") return
val rec = db.findByPurchaseToken(token) ?: return
rec.status = "ACTIVE"
rec.gracePeriod = false
rec.onHold = false
rec.renewalDate = sub.lineItems.firstOrNull()?.expiryTime
db.update(rec)
}
After account hold expires without recovery, you get SUBSCRIPTION_CANCELED or SUBSCRIPTION_EXPIRED. Treat it like any cancellation: revoke, update, optional resubscribe email.
Let a single function branch on the server reported status. Do not try to derive this from queryPurchasesAsync().
// PBL 9.x
fun handleSubscriptionState(status: SubscriptionStatus) {
when {
status.isOnHold -> {
revokeEntitlement()
showAccountHoldScreen()
}
status.isInGracePeriod -> {
// keep access, show dismissible banner
showGracePeriodBanner()
}
status.isActive -> grantEntitlement()
}
}
showInAppMessages() for payment issuesCall at natural moments (app launch, entering a subscription gated feature, or when server flags indicate grace or hold). The TRANSACTIONAL category covers both grace period and account hold. If there is nothing to show, the call returns NO_ACTION_NEEDED.
// PBL 9.x
fun showPaymentRecovery(activity: Activity) {
val params = InAppMessageParams.newBuilder()
.addInAppMessageCategoryToShow(
InAppMessageParams
.InAppMessageCategoryId.TRANSACTIONAL
).build()
billingClient.showInAppMessages(activity, params) { r ->
if (r.responseCode ==
InAppMessageResult.InAppMessageResponseCode
.SUBSCRIPTION_STATUS_UPDATED
) refreshSubscriptionStatus()
}
}
On SUBSCRIPTION_STATUS_UPDATED, re sync with your backend. Google has confirmed the payment was fixed inside the dialog, but your server flag is still stale until the SUBSCRIPTION_RECOVERED RTDN lands.
Use this as the CTA target from banners, the hold screen, and notifications.
// PBL 9.x
fun openSubscriptionManagement(ctx: Context, pkg: String) {
val uri = Uri.parse(
"https://play.google.com/store/account/" +
"subscriptions?package=$pkg"
)
ctx.startActivity(Intent(Intent.ACTION_VIEW, uri))
}
SUBSCRIPTION_IN_GRACE_PERIOD arrives, verify entitlement stays on and the banner renders.SUBSCRIPTION_ON_HOLD arrives, verify entitlement is revoked and the hold screen blocks premium features.SUBSCRIPTION_RECOVERED arrives, verify flags clear, entitlement restores, and renewalDate equals the new expiryTime from SubscriptionPurchaseV2.SUBSCRIPTION_CANCELED or SUBSCRIPTION_EXPIRED arrives, verify the resubscribe UI appears.SUBSCRIPTION_IN_GRACE_PERIOD immediately; the silent ~1 day must pass first.