Imported from revenuecat/ai-toolkit (revenuecat-play-billing/skills/rc-subscription-states/SKILL.md) via skills.sh. Install upstream with npx skills add revenuecat/ai-toolkit --skill rc-subscription-states. Copyright stays with the author (Apache-2.0; see LICENSE).

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 seven states versus RevenueCat's boolean

Rolling your own tracker with the Google Play Developer API means mapping seven 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

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

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

Drive state aware UI

isActive gates access; the other fields explain context.

fun updateUI(entitlement: EntitlementInfo?) {
    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

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.

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

The listener does not fire when the SDK starts with a cache hit and nothing changed. Always call awaitCustomerInfo() on launch in addition to setting the listener.

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