Subscription States

Subscription States

Decide whether a user has access, and drive state aware UI, using CustomerInfo and EntitlementInfo on Android.

Phase 1: Discover

Confirm what you are actually checking before you write code.

• Which entitlement identifier gates the feature? (for example pro_access)
• Do you need a plain access boolean, or do you also need to explain why the user has or lacks access (billing issue, canceled but still paid, paused)?
• Do you need the cached value (fast, possibly stale) or a freshly fetched value (server authoritative)?
• Are you refreshing UI once on launch, or reacting to live changes (purchase, restore, background refresh)?

If you only need access on/off, you only need isActive. Everything else is optional context.

Phase 2: Plan

Google's eight states versus RevenueCat's boolean

Rolling your own tracker with the Google Play Developer API means mapping eight subscription states and deciding which grant access.

RevenueCat computes this on the backend from the Google SubscriptionPurchaseV2 resource and exposes the result as one field: EntitlementInfo.isActive. You read a boolean instead of implementing the state machine.

What to read, and when

Decision rules

• Gate features on isActive == true. Nothing else.
• Use billingIssueDetectedAt != null to show a fix payment prompt.
• Use unsubscribeDetectedAt != null with expirationDate to show a renewal reminder while access is still valid.
• Use !willRenew (when no billing issue and no explicit cancel timestamp) to show a non renewing notice.

Phase 3: Execute

Read CustomerInfo and check access

kotlinCopy code
val customerInfo = Purchases.sharedInstance.awaitCustomerInfo()
val hasAccess = customerInfo.entitlements["pro_access"]?.isActive == true

awaitCustomerInfo() returns the disk cache immediately, then refreshes from the network in the background. Entitlement checks stay fast, even offline.

Force a fresh fetch when you must

Use this after a server side grant (for example, a support agent issued a promo).

kotlinCopy code
val fresh = Purchases.sharedInstance.awaitCustomerInfo(
    fetchPolicy = CacheFetchPolicy.FETCH_CURRENT
)

Drive state aware UI

isActive gates access; the other fields explain context.

kotlinCopy code
fun updateUI(entitlement: EntitlementInfo?) {
    if (entitlement != null && !entitlement.isActive && entitlement.billingIssueDetectedAt != null) {
        // Account hold, or an expiry after a billing issue that was never resolved. See revenuecat/payment-recovery.
        showAccountHoldScreen(); return
    }
    if (entitlement == null || !entitlement.isActive) {
        showSubscribeScreen(); return
    }
    showPremiumContent()
    when {
        entitlement.billingIssueDetectedAt != null -> showBillingIssueWarning()
        entitlement.unsubscribeDetectedAt != null ->
            entitlement.expirationDate?.let { showExpiryNotice(it) }
        !entitlement.willRenew -> showNonRenewingNotice()
    }
}

Messaging guide by signal

Identify the user for multi device

kotlinCopy code
val result = Purchases.sharedInstance.awaitLogIn("your_user_id")
val customerInfo = result.customerInfo
val createdNewUser = result.created

awaitLogIn() merges anonymous purchases with the identified user. logOut() starts a fresh anonymous session.

Phase 4: Verify

Listen for CustomerInfo updates

Register a listener so UI reacts to purchases, restores, and background refreshes without manual polling.

kotlinCopy code
Purchases.sharedInstance.updatedCustomerInfoListener =
    UpdatedCustomerInfoListener { info ->
        val active = info.entitlements["pro_access"]?.isActive == true
        updateAccessGate(active)
    }

Setting the listener immediately delivers the cached CustomerInfo if one exists. On a first launch with no cache it fires only after the first fetch, so still call awaitCustomerInfo() on launch to drive the initial UI.

Test matrix

Walk through each case and confirm the UI responds correctly.

Sanity checks

• Access gate flips correctly when the listener fires after a purchase.
• FETCH_CURRENT updates CustomerInfo after a backend grant (promo, refund, support action).
• After logOut(), CustomerInfo reflects an anonymous user and isActive resets accordingly.
• Offline launch still returns cached CustomerInfo and gates access without a network call.

References

• Full chapter