RevenueCat Migration -- Motivation

Readwise's billing logic is extremely complex: 7 subscription states x 3 billing platforms (iOS/Android/web) x 3 current platforms x 2 products (Readwise/Reader) = potentially 252 billing state transitions. Android already uses RevenueCat, but iOS still uses native Apple StoreKit, creating inconsistency and bugs. Migrating iOS to RevenueCat unifies all mobile billing under one system, dramatically simplifies entitlement logic, and unblocks two critical projects: the Readwise 2.0 mobile app (which needs a working upgrade/subscribe flow) and the Bifurcation plan (which requires new Readwise-only and Reader-only subscription plans).

RevenueCat Migration -- Shape

Entered Shape: 2025-11-01 · Owner: @tristan · Initiative: rw-projects

Key decisions

• Migrate iOS in-app purchases to RevenueCat (Android already on RC)
• Server-side migration first: import existing Apple receipts into RevenueCat, validate purchase history
• Use profile.id as RevenueCat app_user_id (same auth system across all apps)
• Switch App Store Connect S2S URL to RevenueCat with forwarding to existing Apple webhook
• One RevenueCat project for Readwise + Reader + future apps
• Don't use RevenueCat on web (Stripe stays -- RC web would cost ~$50K/year)
• Part of broader Billing Bifurcation Refactor with multiple milestones

Scope

• Milestone 1: Audit existing billing state transitions
• Milestone 2: Billing state unification (subscription_state field)
• Milestone 3: Migrate iOS to RevenueCat
• Future: Create new subscription plans on Stripe + RevenueCat

Appetite

• Medium -- primarily Tristan with Arek on Android/mobile side, Rasul on billing audits

RevenueCat Migration -- Build (WIP)

This document is underway while the project is in Build. It will be finalized when the stage completes.

Entered Build: 2025-12-01 · Owner: @tristan · Initiative: rw-projects

Goal

Migrate all mobile billing to RevenueCat and unify billing state logic, unblocking RW 2.0 and subscription bifurcation.

What's been done

• Reader Android RevenueCat integration shipped (Arek, Dec 2025)
• Backend RevenueCat integration merged (Tristan, Dec 2025)
• RevenueCat webhook improvements and billing failure state tracking (Tristan, Jan 2026)
• login() called before purchase fix (Tristan, Jan 2026)
• Migration meeting with RevenueCat engineering team (Jan 27, 2026)
• Webhook gateway refactor (Tristan, Feb 2026)
• Billing flows audit (Rasul, Feb 2026)
• Reader iOS RevenueCat migration merged (Tristan, Feb 25, 2026)
• Webhook routing guards + race condition fix for Reader iOS (Tristan, Feb 2026)
• Google Play subscription management for RC subscribers (Tristan, Mar 2026)
• Arek: singleTop launch mode fix, Android notification fixes for RC

What's in progress

• PR #7662: Transition RevenueCat subscribers properly through subscription states (open since Dec 27)
• PR #8030: Audit RevenueCat dry run vs Apple webhook (open since Feb 4)
• Readwise iOS migration (Reader iOS done, Readwise iOS still needed)
• RW 2.0 mobile upgrade/subscribe flow depends on this (Ibai PR #8715 merged)

What's not done yet

• Readwise iOS app migration to RevenueCat
• New subscription plans (Readwise-only, Reader-only) on Stripe + RevenueCat
• Full billing state transition audit completion
• Final QA across all billing state transitions

Open Questions (for next stage)

• Timeline for Readwise iOS migration vs Reader iOS (which is done)?
• How to handle edge cases in subscriber state transitions during migration?
• When to create the new bifurcated subscription plans?