revenuecat/ai-toolkit

rc-plan-changes

Use this skill when implementing subscription upgrades, downgrades, and plan switches via RevenueCat on Android.

소스 보기

사용 방법

  1. 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
  2. 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
  3. 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/revenuecat/ai-toolkit --skill rc-plan-changes

시작 전 확인

  • 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
  • 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서

원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.

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

ScenarioModeBilling 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 planCHARGE_FULL_PRICEThe 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)

ScenarioModeBilling effect
Upgrade to a higher tierCHARGE_PRORATED_PRICEImmediate 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 trialWITHOUT_PRORATIONImmediate switch, no charge until the trial ends
Upgrade during a free trial, charge nowCHARGE_PRORATED_PRICEImmediate switch, trial ends, prorated charge now
Downgrade to a lower tierDEFERREDSwitch applies at the next renewal (Google's recommendation)
Switch to a prepaid plan (upgrade or downgrade)CHARGE_FULL_PRICEThe 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

MistakeFix
Hardcoding oldProductId as a constantDerive it from customerInfo.activeSubscriptions.firstOrNull()?.substringBefore(":")
Passing "productId:basePlanId" as oldProductIdSlice off the base plan with substringBefore(":")
Picking a trial upgrade mode without deciding whether to keep the trialWITHOUT_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 switchUse CHARGE_FULL_PRICE or WITHOUT_PRORATION; DEFERRED only works across different subscription products
Writing backend code to follow linkedPurchaseTokenRevenueCat does this server side, delete the code
Reading the SKU to decide UI stateRead entitlements[...]?.isActive instead

References

같은 저장소의 Skills

더 많은 Skills

모든 Skills
revenuecat
커뮤니티

create-revenuecat-project

Set up a complete RevenueCat project from scratch — creates apps, products, entitlements, offerings, and packages in the correct order. Use when the user wants to create a new RevenueCat project, configure in-app purchases, set up subscriptions or monetization, or bootstrap IAP infrastructure for iOS, Android, or Web.

1시간 설치 수
2
GitHub Stars
79
업데이트
11월 17일
revenuecat
커뮤니티

rc-cancellations-pauses-winback

Use this skill when surfacing cancellation, pause, and winback state on Android with RevenueCat. Covers reading unsubscribeDetectedAt, billingIssueDetectedAt, pause state and resume date via SubscriptionInfo.autoResumeDate, showManageSubscriptions for the deep link, and the SUBSCRIPTIONPAUSED webhook.

1시간 설치 수
2
GitHub Stars
79
업데이트
11월 17일
revenuecat
커뮤니티

rc-configuring-the-sdk

Use this skill when adding and configuring the RevenueCat Android SDK (purchases-android, artifact com.revenuecat.purchases:purchases) in an app. Covers the Gradle dependency, Purchases.configure with PurchasesConfiguration, initial app user id strategy, and log level.

1시간 설치 수
2
GitHub Stars
79
업데이트
11월 17일
revenuecat
커뮤니티

rc-purchase-flow

Use this skill when implementing a RevenueCat purchase on Android. Covers awaitPurchase, PurchasesTransactionException, reading CustomerInfo entitlements to grant access, restoring purchases, and the six SDK managed steps that happen inside a single call.

1시간 설치 수
2
GitHub Stars
79
업데이트
11월 17일