Terminal
Terminal/Skill
Covers moving an app from StoreKit or Google Play Billing to RevenueCat, or upgrading the RevenueCat SDK to a new major version.
By RevenueCat
Works with
npx skills add revenuecat/ai-toolkit --skill revenuecat-migrateUse this skill when the user wants to either adopt RevenueCat in an app that already ships in app purchases, or upgrade the RevenueCat SDK across a major version.
These two paths share some concepts but have different risks. Identify which one applies before touching code.
Inspect the working directory and pick the first match, from top to bottom:
package.json has a react-native-purchases entry, or react-native as a dependency → read platforms/react-native.md. If expo is also a dependency, note it as an Expo project.pubspec.yaml exists at the project root → read platforms/flutter.md.build.gradle.kts contains a kotlin { … } multiplatform source sets block, or depends on com.revenuecat.purchases:purchases-kmp* → read platforms/kmp.md.build.gradle(.kts) applies com.android.application (and is not KMP) → read platforms/android.md.Package.swift, *.xcodeproj, *.xcworkspace, or Podfile at the project root → read platforms/ios.md.If several match (e.g. an ios/ folder inside a Flutter project), pick the outermost project, the one that owns the build. If still ambiguous, ask the user which platform they want to configure.
Ask the user (or infer from the codebase):
Both paths can happen at once (e.g. adopt RC today on the latest major version). Run Path A first, then Path B if needed.
Observer mode is the key lever for adopting RevenueCat without rewriting purchase code. The SDK observes transactions that your existing StoreKit / Billing code processes, sends them to the RevenueCat backend for validation, and updates subscriber state, but does not initiate or finish the transactions. Your existing purchase UI, receipt validation, and transaction finishing stay in place.
Set this at configure time:
purchasesAreCompletedBy: .myApp together with storeKitVersion: .storeKit1 (or .storeKit2) on Configuration.Builder. They are separate parameters, not a single associated value.purchasesAreCompletedBy(PurchasesAreCompletedBy.MY_APP) on PurchasesConfiguration.Builder.const PurchasesAreCompletedByMyApp(storeKitVersion: StoreKitVersion.storeKit2) to PurchasesConfiguration.purchasesAreCompletedBy: { type: PURCHASES_ARE_COMPLETED_BY_TYPE.MY_APP, storeKitVersion: STOREKIT_VERSION.STOREKIT_2 } in the configure call.The default is RevenueCat completed (REVENUECAT / .revenueCat), where the SDK owns the full flow.
Once stable in observer mode, you can optionally cut over to full RevenueCat mode later by removing your own purchase plumbing and dropping the purchasesAreCompletedBy override.
When purchasesAreCompletedBy is set to myApp, RevenueCat does not finish transactions on iOS or acknowledge on Android. Your existing code must continue to do that. If you remove the myApp flag while leaving your old transaction finishing code in place, transactions get acknowledged twice and subscriber state can appear inconsistent.
Exactly one side must own finishing / acknowledging. Pick a side and remove the other.
If the app already has its own authentication system, call Purchases.logIn(existingAppUserID) once RevenueCat is configured. This attaches the prior purchase history to the right RevenueCat user on ingestion. Without this step, existing purchases get recorded against an anonymous RC user and cannot be matched to the app's actual user records later.
Only skip this if the app has no notion of authenticated users.
Major version upgrades change configuration shape, drop deprecated APIs, and shift default behavior in ways that move with each release. This skill does not duplicate the per-version diff. Read the canonical sources from the SDK repo:
*MIGRATION*.md or a migrations/ directory. Major bumps usually ship a dedicated guide there. The release notes for the major version on the repo's GitHub releases page typically link to it.Treat the SDK repo's docs as authoritative. Any version-specific diff written here would drift out of date. The platform file under platforms/ for your target lists the exact repo to consult.
Work in this order on every platform:
Read the platform file that matches detection:
platforms/ios.mdplatforms/android.mdplatforms/kmp.mdplatforms/flutter.mdplatforms/react-native.mdEach platform file covers both migration paths for that platform.
Do not declare migration done until: