사용 방법
- 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
- 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
- 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/revenuecat/ai-toolkit --skill rc-plan-changes시작 전 확인
- 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
- 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.
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
CustomerInfofromPurchases.sharedInstance.awaitCustomerInfo()or a cached value from a recent listener callback. - You have the target
Packageresolved fromofferings.current(see rc-subscriptions). - RevenueCat SDK 10.3.0 or later is on the classpath (
StoreReplacementModearrived 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 forDEFERRED.
Skip this skill if the user has no active subscription. For a fresh purchase, use 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.
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_planfor you, but the intent is clearer when you slice it yourself. CustomerInfo.activeSubscriptionsuses theproductId:basePlanIdshape.substringBefore(":")gives you the correct value.
Phase 4: Verify
After the suspending call returns, read the updated CustomerInfo:
customerInfo.activeSubscriptionsnow contains the newproductId:basePlanId.customerInfo.entitlements["pro"]?.isActivestaystrueacross the switch; do not gate UI on the SKU string.- For
DEFERREDmode,activeSubscriptionsstill 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 |