Setting up RevenueCat on a new app is low-stakes: nobody’s paying yet, so a mistake costs you a day of debugging. Migrating an app that already has live, paying subscribers off a homegrown StoreKit implementation is a different job entirely — a mistake can silently revoke access for a paying customer, or worse, double-charge them. The sequence below is built around never having a moment where RevenueCat is the only source of truth until it’s been proven correct against the old system.
1. Why This Migration Is Riskier Than a New Build
1
Don’t touch products or pricing during the migration
Keep every existing product ID, price, and subscription group exactly as-is. The migration should be invisible to App Store Connect — you’re changing how you validate and track existing subscriptions, not what’s being sold.
2
Import historical transaction history
RevenueCat can backfill a subscriber’s purchase history from Apple’s transaction data, so existing subscribers show up correctly without needing to repurchase.
3
Run both systems in parallel before cutover
The legacy entitlement check stays authoritative while RevenueCat runs alongside it, logging what it would have decided. Compare the two before RevenueCat ever gates access.
4
Roll out to a small percentage first
Cut a small cohort over to RevenueCat as the source of truth, watch for support tickets and entitlement mismatches for a few days, then expand.
2. The Migration Sequence We Use
Week 1
Audit existing entitlement logic; document every edge case it currently handles
Audit
Week 1
Configure RevenueCat project, import historical transactions from Apple
Setup
Week 2
Ship the RevenueCat SDK behind a flag — it observes and logs, but the legacy system still decides access
Dark launch
Week 2–3
Validate RevenueCat’s entitlement decision matches the legacy system for 100% of active subscribers
Validation
Week 3
Cut over: RevenueCat becomes the source of truth, legacy system becomes a fallback only
Cutover
Week 4
Remove legacy entitlement code once cutover has held cleanly for a full billing cycle
Cleanup
Gotcha
App Store Server Notifications need to point wherever your source of truth is. If your backend was receiving Apple’s server notifications directly, decide explicitly whether RevenueCat or your own endpoint owns that during and after the transition — misconfiguring this is the most common way teams end up with two systems that silently disagree.
3. Safe Pattern vs. Risky Pattern
What we do
Cutover styleStaged, validated
Legacy systemFallback, then removed
RolloutSmall cohort first
What goes wrong with a big-bang cutover
Cutover styleAll users, all at once
Legacy systemDeleted immediately
RolloutNo comparison window
If your app spans both iOS and Android and you’re consolidating onto RevenueCat for the first time, the same staged-cutover principle applies on both platforms — see our Flutter integration guide for the cross-platform entitlement model, and once you’re live, our analytics piece covers what to do with the subscriber data once RevenueCat is the source of truth.
Migrating a live subscription app off custom StoreKit code?
Tell us how many active subscribers you’re migrating and we’ll map a cutover plan that doesn’t put a single one of them at risk.
Start the Conversation →
