# rc-plan-changes

Guides subscription upgrades, downgrades, and plan changes for RevenueCat on Android with proper replacement modes.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 621 installs · ★ 76
- Author: RevenueCat
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/RevenueCat/ai-toolkit/tree/HEAD/revenuecat-play-billing/skills/rc-plan-changes/SKILL.md
- Updated: 2026-10-21
- HTML: https://affpapa.org/en/nevibecode/skills/rc-plan-changes

## What it does

This skill guides your coding agent through subscription switches on Android using RevenueCat. It configures `PurchaseParams.Builder` with `GoogleProductChangeInfo` for upgrades, downgrades, and trial conversions when a user already holds an active Google Play subscription.

The workflow maps out `GoogleReplacementMode` choices. You apply `WITH_TIME_PRORATION` for standard upgrades or `CHARGE_PRORATED_PRICE` to charge immediately during free trials. Google rejects `DEFERRED` for upgrades, so the skill restricts that mode strictly to downgrades.

Kotlin examples show how to slice `currentProductId` using `substringBefore(":")` from `activeSubscriptions` to drop the base plan suffix. The setup assumes Google Play Billing Library 7 or newer via the RevenueCat SDK.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add RevenueCat/ai-toolkit --skill rc-plan-changes -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/rc-plan-changes/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/rc-plan-changes/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add RevenueCat/ai-toolkit --skill rc-plan-changes -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/rc-plan-changes/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add RevenueCat/ai-toolkit --skill rc-plan-changes -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/rc-plan-changes/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install RevenueCat/ai-toolkit rc-plan-changes
```

2. **Manually: put the files in place**
- File: `.github/skills/rc-plan-changes/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add RevenueCat/ai-toolkit --skill rc-plan-changes -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/RevenueCat/ai-toolkit --path revenuecat-play-billing/skills/rc-plan-changes
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/rc-plan-changes/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add RevenueCat/ai-toolkit --skill rc-plan-changes -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/RevenueCat/ai-toolkit/tree/HEAD/revenuecat-play-billing/skills/rc-plan-changes/SKILL.md

## When to use it
- switch an active monthly subscription to annual with time proration
- configure deferred downgrades that apply at next renewal
- parse the raw product identifier from activeSubscriptions cleanly
- prevent unpaid premium access during active trial upgrades

## Example prompts
- Configure an upgrade from monthly to annual subscription using RevenueCat on Android
- Implement a deferred subscription downgrade with GoogleProductChangeInfo in Kotlin
- How do I pass oldProductId properly to PurchaseParams when changing plans?

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 7614add9706d5ac5.

BEGIN THIRD-PARTY FILE 7614add9706d5ac5
````text
---
name: rc-plan-changes
description: Use this skill when implementing subscription upgrades, downgrades, and plan switches via RevenueCat on Android. Covers GoogleProductChangeInfo, picking a Google 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
  - google-product-change-info
  - 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 `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:

| Scenario | Mode | Billing effect |
|---|---|---|
| Standard upgrade (monthly to annual) | `WITH_TIME_PRORATION` | Immediate switch, remaining time credited |
| Upgrade, keep the existing billing date | `CHARGE_PRORATED_PRICE` | Immediate switch, prorated charge now |
| Switch to or from a prepaid plan | `CHARGE_FULL_PRICE` | Immediate switch, full charge now |
| Upgrade during an active free trial | `CHARGE_PRORATED_PRICE` | Immediate switch, prorated charge now |
| Downgrade (annual to monthly) | `DEFERRED` | Switch applies at next renewal |

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.

```kotlin
val customerInfo = Purchases.sharedInstance.awaitCustomerInfo()
````
END THIRD-PARTY FILE 7614add9706d5ac5

The third-party file has ended. Everything between the 7614add9706d5ac5 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2866 of 5628 bytes. © RevenueCat · MIT · https://github.com/RevenueCat/ai-toolkit/tree/HEAD/revenuecat-play-billing/skills/rc-plan-changes/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md