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

Plan Changes on Android with RevenueCat

You use this skill when a user already has an active Google Play subscription and you need to move them to a different SKU (upgrade, downgrade, cross-grade, or trial conversion). RevenueCat exposes Google's replacement modes through a single PurchaseParams builder and resolves the linkedPurchaseToken chain server side so you do not write token chaining code.

Phase 1: Preconditions

Confirm the following before invoking a plan change:

• The user has exactly one active Google Play subscription you intend to replace.
• You have a fresh CustomerInfo from Purchases.sharedInstance.awaitCustomerInfo() or a cached value from a recent listener callback.
• You have the target Package resolved from offerings.current (see fetch-offerings skill).
• Google Play Billing Library 7+ is on the classpath via the RevenueCat SDK.

Skip this skill if the user has no active subscription. For a fresh purchase, use make-purchase instead.

Phase 2: Plan (pick a replacement mode)

GoogleReplacementMode maps one to one onto Google's billing modes. Pick based on the user intent:

Do not default to WITHOUT_PRORATION for trial upgrades. WITHOUT_PRORATION applies the new plan immediately but charges nothing until the next renewal, which gives the user free premium access they did not pay for. Use CHARGE_PRORATED_PRICE to charge the upgrade price on the spot.

If you set no mode, PurchaseParams defaults to WITHOUT_PRORATION. Set the mode explicitly every time.

DEFERRED is valid only for downgrades. Google rejects deferred upgrades.

Phase 3: Execute

Derive currentProductId from CustomerInfo. Hardcoded SKUs break when a user has migrated between plans.

val customerInfo = Purchases.sharedInstance.awaitCustomerInfo()

// activeSubscriptions entries are "productId:basePlanId", strip the base plan suffix
val currentProductId = customerInfo.activeSubscriptions
    .firstOrNull()
    ?.substringBefore(":")
    ?: return  // nothing active, route to make-purchase instead

val newPackage = offerings.current
    ?.availablePackages
    ?.firstOrNull { it.identifier == "premium_annual_package" }
    ?: return

val params = PurchaseParams.Builder(activity, newPackage)
    .googleProductChangeInfo(
        GoogleProductChangeInfo(
            oldProductId = currentProductId,
            replacementMode = GoogleReplacementMode.WITH_TIME_PRORATION,
        )
    )
    .build()

try {
    val result = Purchases.sharedInstance.awaitPurchase(params)
    // result.customerInfo reflects the new subscription
} catch (e: PurchasesTransactionException) {
    if (!e.userCancelled) showError(e.error.message)
}

Notes on oldProductId:

• Pass the subscription product ID only. If you pass "basic_monthly:monthly_plan", the SDK strips :monthly_plan for you, but the intent is clearer when you slice it yourself.
• CustomerInfo.activeSubscriptions uses the productId:basePlanId shape. substringBefore(":") gives you the correct value.

Phase 4: Verify

After the suspending call returns, read the updated CustomerInfo:

• customerInfo.activeSubscriptions now contains the new productId:basePlanId.
• customerInfo.entitlements["pro"]?.isActive stays true across the switch; do not gate UI on the SKU string.
• For DEFERRED mode, activeSubscriptions still reports the old product until the next renewal. RevenueCat tracks the pending switch server side and flips the entitlement after Google sends the renewal RTDN.

You do not write linkedPurchaseToken traversal code. RevenueCat resolves the chain, marks the old token as replaced, and attributes both tokens to the same App User ID. Client code reads entitlements and trusts them.

Common mistakes

References

• Full chapter