Payment Recovery

Payment Recovery: Grace Period and Account Hold

Google 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.

Phase 1: Understand

Map the stages, the RTDN for each transition, and the entitlement you should hold.

Key facts to internalize before writing any code:

• The silent grace period of about 1 day always applies, even with a 0 day configuration. It is folded into any longer grace period you set (a 7 day window means 7 total days, not 7 + 1).
• Client side 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.
• Grace period expiryTime points to the end of the grace window, not the original renewal date.
• On recovery from account hold, Google moves the billing date to the recovery date; recovery during grace period keeps the original renewal date. Persist the new expiryTime from SubscriptionPurchaseV2 either way; cached pre failure dates will be wrong.
• If you disable account hold, the subscription cancels immediately after grace period ends. Google's default enables both, with account hold = 60 days minus the grace period.

Phase 2: Plan the dunning policy

Decide these rules before you touch code. The rest of the skill is mechanical once this is set.

Stage to action mapping

Messaging cadence during recovery

• Day 0 of grace period: push notification immediately on SUBSCRIPTION_IN_GRACE_PERIOD plus banner in app.
• Day 3 of grace period: email reminder with deep link to payment update.
• Transition to account hold: push notification plus switch app UI to full screen hold screen. Revoke entitlement in the same transaction that flips the flag.
• Midway through account hold: second email. Increase urgency wording.
• On SUBSCRIPTION_RENEWED (grace) or SUBSCRIPTION_RECOVERED (hold): clear the relevant flag, restore entitlement if it was revoked, persist the new expiryTime, optional confirmation message.

Rules you should codify

1. Never revoke during grace period. That is Google's guideline and the main retention lever.
2. Always revoke on SUBSCRIPTION_ON_HOLD. Do not wait for the user to open the app.
3. Treat the server flag, not Purchase.isAutoRenewing, as the source of truth for recovery state.
4. On SUBSCRIPTION_RENEWED (grace) or SUBSCRIPTION_RECOVERED (hold), overwrite the cached renewal date with the new expiryTime.
5. When changing grace or account hold durations, extend rather than shorten. Shortening does not affect subscribers already in grace, but it lowers recovery for every later payment failure. If you must shorten, monitor SUBSCRIPTION_ON_HOLD and SUBSCRIPTION_CANCELED volume after the change.

Phase 3: Execute

3.1 Backend: handle the four transition RTDNs

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:

1. Confirm subscriptionState == SUBSCRIPTION_STATE_IN_GRACE_PERIOD.
2. Set gracePeriod = true on the user record. Keep entitlement active.
3. Trigger push notification and queue the day 3 email.

SUBSCRIPTION_ON_HOLD:

1. Confirm subscriptionState == SUBSCRIPTION_STATE_ON_HOLD.
2. Set onHold = true. Revoke the entitlement now.
3. Trigger push notification. Queue the midway hold email.

SUBSCRIPTION_RENEWED while gracePeriod == true (recovery during grace period; renewal date unchanged):

1. Confirm subscriptionState == SUBSCRIPTION_STATE_ACTIVE.
2. Clear gracePeriod on the user record. Entitlement was never revoked.
3. Persist the new expiryTime. Optional confirmation message.

SUBSCRIPTION_RECOVERED (recovery from account hold, or resume from pause):

kotlinCopy code
// 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 (3), then SUBSCRIPTION_EXPIRED (13). Treat it like any cancellation: revoke, update, optional resubscribe email.

3.2 Client: drive UI from server flags

Let a single function branch on the server reported status. Do not try to derive this from queryPurchasesAsync(): by default it omits subscriptions in account hold. On PBL 8.1+ you can query with QueryPurchasesParams.newBuilder().setProductType(ProductType.SUBS).includeSuspendedSubscriptions(true).build(); a purchase with isSuspended == true is on hold or paused, so do not grant access and deep link to the subscriptions center instead.

kotlinCopy code
// PBL 9.x
fun handleSubscriptionState(status: SubscriptionStatus) {
    when {
        status.isOnHold -> {
            revokeEntitlement()
            showAccountHoldScreen()
        }
        status.isInGracePeriod -> {
            // keep access, show dismissible banner
            showGracePeriodBanner()
        }
        status.isActive -> grantEntitlement()
    }
}

3.3 Client: showInAppMessages() for payment issues

Call 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.

kotlinCopy code
// 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_RENEWED (grace) or SUBSCRIPTION_RECOVERED (hold) RTDN lands; send r.purchaseToken to your backend to re fetch now.

3.4 Deep link to Play Store subscription management

Use this as the CTA target from banners, the hold screen, and notifications.

kotlinCopy code
// PBL 9.x
fun openSubscriptionManagement(ctx: Context, pkg: String, productId: String?) {
    val base = "https://play.google.com/store/account/subscriptions"
    val uri = Uri.parse(
        if (productId != null) "$base?sku=$productId&package=$pkg" else base
    )
    ctx.startActivity(Intent(Intent.ACTION_VIEW, uri))
}

3.5 Verification checklist

• Grace period path: trigger a test renewal failure, confirm SUBSCRIPTION_IN_GRACE_PERIOD arrives, verify entitlement stays on and the banner renders.
• Hold path: wait for grace to expire, confirm SUBSCRIPTION_ON_HOLD arrives, verify entitlement is revoked and the hold screen blocks premium features.
• Recovery path: fix the payment method, confirm SUBSCRIPTION_RENEWED arrives if recovering from grace or SUBSCRIPTION_RECOVERED if recovering from hold, verify flags clear, entitlement restores, and renewalDate equals the new expiryTime from SubscriptionPurchaseV2.
• Terminal path: let account hold expire, confirm SUBSCRIPTION_CANCELED (3), then SUBSCRIPTION_EXPIRED (13) arrive, verify the resubscribe UI appears.
• Silent window: confirm a fresh renewal failure does not fire SUBSCRIPTION_IN_GRACE_PERIOD immediately; the silent ~1 day must pass first.

References

• Full chapter