--- name: rc-plan-changes description: Use this skill when implementing subscription upgrades, downgrades, and plan switches via RevenueCat on Android. Covers StoreReplacementMode, picking a replacement mode, and letting the SDK manage linkedPurchaseToken chaining. license: Apache-2.0; see LICENSE metadata: author: RevenueCat source: revenuecat-handbook chapter 7 keywords: - android - revenuecat - upgrade - downgrade - store-replacement-mode - replacement-mode --- # 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 [rc-subscriptions](../rc-subscriptions/)). - RevenueCat SDK 10.3.0 or later is on the classpath (`StoreReplacementMode` arrived in 10.3.0). This skill was checked against 11.1.0, which brings Play Billing Library 9.1.0. - If you will use `DEFERRED`, Google Real Time Developer Notifications must be connected to RevenueCat (RevenueCat Play app settings > Connect to Google, then paste the topic in Play Console > Monetize > Monetization setup). RevenueCat requires this for `DEFERRED`. Skip this skill if the user has no active subscription. For a fresh purchase, use [rc-purchase-flow](../rc-purchase-flow/) instead. ## Phase 2: Plan (pick a replacement mode) `StoreReplacementMode` is the type `PurchaseParams.Builder.replacementMode()` takes: a class with five constants (`CHARGE_FULL_PRICE`, `CHARGE_PRORATED_PRICE`, `DEFERRED`, `WITHOUT_PRORATION`, `WITH_TIME_PRORATION`; there is no `KEEP_EXISTING`), not an enum, so a `when` over it needs an `else` branch. Google validates the mode differently depending on whether the switch stays within one subscription product or crosses to a different one, so decide that first. Check whether `oldProductId` and the new product share the same Google Play subscription ID and only the base plan or offer differs (for example `premium:monthly` to `premium:annual`), or point at different subscription products entirely (for example `basic` to `premium`). Switching to a prepaid plan, within one subscription or to a different subscription product, allows only `CHARGE_FULL_PRICE`; any other mode fails the purchase. ### Same subscription, different base plan or offer | Scenario | Mode | Billing effect | |---|---|---| | Change billing period (for example monthly and annual base plans of one subscription) | `CHARGE_FULL_PRICE` (charge now) or `WITHOUT_PRORATION` (charge at next renewal) | Any other mode fails the purchase | | Switch to a prepaid plan | `CHARGE_FULL_PRICE` | The only valid mode | Google allows only `CHARGE_FULL_PRICE` or `WITHOUT_PRORATION` when switching base plans or offers of the same subscription product to an auto renewing plan. `WITH_TIME_PRORATION`, `CHARGE_PRORATED_PRICE`, and `DEFERRED` fail the purchase in this case. ### Different subscription product (tier change) | Scenario | Mode | Billing effect | |---|---|---| | Upgrade to a higher tier | `CHARGE_PRORATED_PRICE` | Immediate switch, prorated charge, same billing date (only when the price per unit of time rises) | | Change billing period across different subscription products (for example a monthly product to an annual product) | `CHARGE_FULL_PRICE` (charge now) or `DEFERRED` (at the next renewal) | `CHARGE_PRORATED_PRICE` fails unless the price per unit of time rises | | Upgrade during a free trial, keep the trial | `WITHOUT_PRORATION` | Immediate switch, no charge until the trial ends | | Upgrade during a free trial, charge now | `CHARGE_PRORATED_PRICE` | Immediate switch, trial ends, prorated charge now | | Downgrade to a lower tier | `DEFERRED` | Switch applies at the next renewal (Google's recommendation) | | Switch to a prepaid plan (upgrade or downgrade) | `CHARGE_FULL_PRICE` | The only valid mode; any other mode fails the purchase | Both free trial options are valid; pick based on whether the user should keep the trial or be charged immediately. If you set no mode, `PurchaseParams` defaults to `WITHOUT_PRORATION`. Set the mode explicitly every time. `DEFERRED` applies the change at the next renewal for upgrades or downgrades across different subscription products, except to a prepaid plan (Google recommends it for downgrades). It is not valid for a base plan or offer switch within the same subscription; use `CHARGE_FULL_PRICE` or `WITHOUT_PRORATION` there instead. ## Phase 3: Execute Derive `currentProductId` from `CustomerInfo`. Hardcoded SKUs break when a user has migrated between plans. ```kotlin 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 purchase-flow instead // Upgrading to a different, higher subscription tier: use CHARGE_PRORATED_PRICE (Phase 2) val newPackage = offerings.current ?.availablePackages ?.firstOrNull { it.identifier == "premium_tier_package" } // a different subscription product ?: return val params = PurchaseParams.Builder(activity, newPackage) .oldProductId(currentProductId) .replacementMode(StoreReplacementMode.CHARGE_PRORATED_PRICE) .build() try { val result = Purchases.sharedInstance.awaitPurchase(params) // result.customerInfo reflects the new subscription } catch (e: PurchasesTransactionException) { if (!e.userCancelled) showError(userFacingMessage(e.error)) // log e.error.message; mapping in rc-error-handling } ``` Import `com.revenuecat.purchases.models.StoreReplacementMode`. There is no `GoogleProductChangeInfo` in the SDK; `GoogleReplacementMode` and `.googleReplacementMode()` are deprecated since 10.3.0. Both setters write the same value, so whichever you call last wins; use `.replacementMode()` only. 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 | Mistake | Fix | |---|---| | Hardcoding `oldProductId` as a constant | Derive it from `customerInfo.activeSubscriptions.firstOrNull()?.substringBefore(":")` | | Passing `"productId:basePlanId"` as `oldProductId` | Slice off the base plan with `substringBefore(":")` | | Picking a trial upgrade mode without deciding whether to keep the trial | `WITHOUT_PRORATION` keeps the trial and charges nothing until it ends; `CHARGE_PRORATED_PRICE` ends the trial now and charges the prorated price | | Using `DEFERRED` for a same subscription base plan or offer switch | Use `CHARGE_FULL_PRICE` or `WITHOUT_PRORATION`; `DEFERRED` only works across different subscription products | | Writing backend code to follow `linkedPurchaseToken` | RevenueCat does this server side, delete the code | | Reading the SKU to decide UI state | Read `entitlements[...]?.isActive` instead | ## References - [Full chapter](https://www.revenuecat.com/guides/revenuecat-android-sdk/subscription-upgrades-and-downgrades)