Compose Multiplatform subscriptions: one KMP layer for iOS and Android
A subscription feature that exists twice — once against Google Play Billing, once against StoreKit — doubles the surface area for bugs and drift. This guide builds the alternative: a Kotlin Multiplatform app whose subscription logic lives in commonMain, with platform entry points doing only the initialization each store requires. You will configure products and entitlements, add the KMP artifacts, link the iOS native framework, gate a premium screen, run a purchase, and render a paywall designed in the dashboard.
What the finished app does
The target app lists premium articles. Until the user is entitled, the article body fades into a join prompt. Tapping the prompt opens a paywall whose layout and packages come from the dashboard. A purchase runs through the native store dialog, and the entitlement state refreshes so the article unlocks without a manual reload. The same screen runs on iPhone and Android from one Compose UI.
The project layout is a conventional multi-module KMP structure: a composeApp module with commonMain, androidMain, and iosMain; feature modules for home, article, paywalls, and subscriptions; and core modules for data, network, and design system. All subscription logic in this walkthrough sits in commonMain.
Dashboard prerequisites
Four things must exist before code:
- A project with one Android app and one iOS app, each linked to its store credentials.
- Products imported from Google Play Console and App Store Connect.
- An entitlement named premium (or an identifier of your choosing).
- An offering with one or more packages attached and marked as the current offering.
Two codelabs cover the dashboard side end to end: the Google Play integration codelab and the App Store integration codelab. The two screens that matter most are the entitlement — the unit your code checks — and the offering — what the app fetches at runtime and can change without a new build. After both apps are configured, copy the public SDK API keys from Project Settings > API Keys; there is one per platform and both are used in the initialization step.
Step 1: Add the KMP artifacts
Two artifacts make up the SDK: purchases-kmp-core carries the subscription logic, and purchases-kmp-ui carries the Compose paywall component. Maven Central publishes both under one version coordinate shaped like <sdk>+<hybrid-common>. That trailing segment is not decoration — the iOS pod link depends on it, so leave it in place.
Declare the version and libraries in gradle/libs.versions.toml, then add both dependencies inside the commonMain source set of the app module's build.gradle.kts (in the demo project, composeApp/build.gradle.kts). Android and iOS consume the same commonMain dependency; there is no separate androidMain dependency block, because the KMP artifact carries platform-specific bindings internally.
Linking the iOS native framework
The KMP SDK depends on PurchasesHybridCommon, a native iOS framework wrapping StoreKit. The cleanest route is the Kotlin CocoaPods plugin, applied to the composeApp module. Then declare both pods inside the kotlin { cocoapods { ... } } block, pinning the pod version to the same major as the purchases-kmp artifact so the Kotlin and Swift sides agree on protocol shapes.
Run ./gradlew podInstall once. Gradle generates a .podspec for the shared module and writes a Podfile.lock next to the iOS app; from then on, opening the iOS workspace in Xcode pulls dependencies through CocoaPods. The SDK's Kotlin/Native interop bindings are still flagged experimental, so opt in to kotlinx.cinterop.ExperimentalForeignApi inside any iOS source set that touches them. That completes setup — no platform-specific source files are needed yet.
Step 2: Initialize Purchases per platform
Purchases is a singleton. Configure it once early in the app lifecycle; every later call goes through Purchases.sharedInstance. Initialization is the only place Android and iOS code diverge, and only because each platform has its own entry point.
On Android, configure from Application.onCreate. The PurchasesConfiguration(apiKey) builder is a small DSL where you can set appUserId, purchasesAreCompletedBy, verificationMode, and other options. Passing appUserId = null makes the SDK generate an anonymous identifier in the form $RCAnonymousID:<uuid>; when the user later signs in to your backend, Purchases.sharedInstance.logIn(userId) transfers purchases to that account. Register the Application class and the INTERNET permission in AndroidManifest.xml.
On iOS, configure from the SwiftUI App struct, importing the native purchases pod rather than the KMP wrapper, because configuration runs in Swift before the Kotlin runtime starts. ContentView then hosts the shared Compose surface inside a UIViewControllerRepresentable, and the Kotlin side exposes a one-line MainViewController() in iosMain. App is the same @Composable that MainActivity calls on Android.
Why the split? Configuring Purchases is not a passive registration — it opens the store connection right away. Android hands off to BillingClient to establish a session; iOS installs a StoreKit transaction listener. Each of those must be live before the first Compose frame, and neither can be reached from shared code, so configuration stays in the platform entry points.
Step 3: Check entitlements from common code
After configuration, the premium question can be answered from any commonMain call site. Every callback API in the KMP SDK has a suspend counterpart built for coroutines; the one this screen needs is awaitCustomerInfo().
CustomerInfo.entitlements is a map keyed by the entitlement identifier defined in the dashboard. Each value is an EntitlementInfo carrying an isActive flag, an expirationDate, a willRenew boolean, and a store enum identifying the platform the purchase came from. For access decisions, only isActive matters — the entitlement is active whether the user subscribed through the App Store, Google Play, Stripe, or a promotional grant from support.
Most apps wrap this in a repository so the rest of the app can collect a Flow. The demo defines PaywallsRepository in core/data with fetchOffering, fetchCustomerInfo, and awaitPurchase. The fetchCustomerInfo implementation is a thin Flow wrapper around the SDK call, with Dispatchers.IO keeping network work off the main thread. A ViewModel collects that flow into a StateFlow<CustomerInfo?>, and the Compose UI reads it like any other state.
In the demo's article detail screen, DetailsContent applies a fadingEdge modifier when isEntitled is false: subscribed users read to the end, free users see the first paragraphs fade into a Join Now call to action. The same composable runs on both platforms.
Step 4: Run a purchase from commonMain
Buying a package takes two suspend calls in sequence: load the current offering, then hand one of its packages to awaitPurchase. From there the SDK drives the store — it presents Google Play's billing dialog or StoreKit's purchase sheet, confirms the receipt with the store, and reports the transaction to the subscription backend.
Offering exposes convenience accessors for common cadences (monthly, annual, lifetime) plus a generic availablePackages list for custom plan pickers. The demo wraps this in PaywallsRepository.awaitPurchase(packageId), which finds the package by identifier and calls awaitPurchase on it.
Two things to know about the return value. The StoreTransaction is informational only: by the time awaitPurchase resumes, the receipt has already been validated server-side and CustomerInfo updated on the backend. And the next awaitCustomerInfo() call reflects the new entitlement, so any UI bound to the customerInfo flow recomposes automatically — no manual invalidation needed.
A cancelled store dialog is not a failure. The SDK raises a PurchasesException with code PurchaseCancelled; catch that case and return quietly instead of surfacing an error.
Step 5: Drop in a server-driven paywall
Hand-building the package picker is optional. The Paywall Editor lets you compose the whole screen in the dashboard and revise it later without a new build, and the purchases-kmp-ui artifact supplies a Paywall composable that draws that configuration identically on Android and iOS.
In KMP code the paywall screen is a single Paywall call. PaywallOptions is where you pass callbacks for dismissal, purchase completion, and restore. With no offering passed, the component renders the current offering assigned to the user in the dashboard; during an A/B test, the SDK selects the variant for that user and attributes conversion to the right experiment arm.
Everything visual — which packages appear, how the recommended plan is highlighted, trial CTA copy, and which offering displays — is dashboard-configurable. Headline copy or layout can change in the morning, conversion metrics watched in the afternoon, and the change reverted with a click if the variant underperforms, all without a store review cycle.
How responsibilities line up
In a finished KMP project, the demo organizes code by module:
- composeApp is the only module with platform-specific code. androidMain configures Purchases from the Application, iosMain exposes MainViewController() to SwiftUI, and commonMain holds App.kt plus a Navigation Compose NavHost.
- feature/* modules are screens (home, article, paywalls, account, subscriptions). They depend on core/* and contain Compose Multiplatform UI plus ViewModels.
- core/data owns PaywallsRepository, the only place calling Purchases.sharedInstance. Everything else reads Flow<Offering> and Flow<CustomerInfo> from this repository.
- core/model, core/network, core/designsystem, and core/navigation hold data classes, the Ktor client, the theme, and the navigation graph.
The shipped UX follows the same pattern. Subscribed users see the full article and a subscription management screen sourced from the same CustomerInfo object. That screen reads customerInfo.activeSubscriptions, the premium entitlement's isActive flag, and customerInfo.originalAppUserId, and runs unmodified on both platforms — no version checks, no platform conditionals. The code lives once in commonMain and the SDK translates underneath.
Every file shown here is in the cat-paywalls-kmp reference repository. The minimum working integration is the dashboard setup plus the four code steps; everything beyond that is product-specific UI.
Pre-flight checklist and failure distinctions
Before wiring code, confirm each item:
- Both store apps exist in the project and are linked to store credentials.
- Products are imported from both consoles.
- The entitlement identifier used in code matches the dashboard exactly.
- One offering is marked current and contains the packages the UI will show.
- The version coordinate keeps the +<hybrid-common> suffix.
- The iOS pod major matches the purchases-kmp artifact major.
- Purchases.configure runs before any Compose composition on both platforms.
Distinguish these outcomes when a purchase does not complete:
- User cancelled the store dialog: PurchasesException with code PurchaseCancelled — a no-op, not a failure to report.
- No current offering configured: the offering fetch returns nothing and the purchase helper raises an error — a dashboard configuration problem, not a billing problem.
- Package identifier not found in the current offering: the repository helper raises a not-found error — a mismatch between UI and dashboard, not a store rejection.
- Any other exception: surfaced as Result.failure by the repository wrapper and worth logging.
For access decisions, read only the entitlement's isActive flag. The store enum and expirationDate are useful for display, not for gating.
| Field | Where it lives | Use in this app |
|---|---|---|
| entitlements["premium"] | CustomerInfo | Access gate; check isActive |
| isActive | EntitlementInfo | The only flag needed for gating |
| expirationDate | EntitlementInfo | Display of renewal timing |
| willRenew | EntitlementInfo | Display of renewal status |
| store | EntitlementInfo | Identify originating platform for display |
| activeSubscriptions | CustomerInfo | Subscription management screen |
| originalAppUserId | CustomerInfo | Subscription management screen |
Field names and roles as described in the captured technical walkthrough; verify against the current SDK reference before shipping.
| Module | Responsibility | Platform-specific? |
|---|---|---|
| composeApp | App.kt, NavHost, Android Application init, iOS MainViewController bridge | Yes (androidMain, iosMain) |
| feature/* | Screens and ViewModels in Compose Multiplatform | No |
| core/data | PaywallsRepository; sole caller of Purchases.sharedInstance | No |
| core/model | Data classes | No |
| core/network | Ktor client | No |
| core/designsystem | Theme | No |
| core/navigation | Navigation graph | No |
Structure reflects the reference demo layout; adapt module names to your own project.
Frequently asked questions
Why can't Purchases.configure run in commonMain?
Configuration touches the platform billing client immediately: Android opens a BillingClient connection and iOS registers a StoreKit transaction listener. Both must happen before Compose composition begins, so configuration belongs in each platform's entry point.
What should happen when a user cancels the purchase dialog?
The SDK throws a PurchasesException with code PurchaseCancelled. Treat it as a no-op rather than an error, so a deliberate cancellation doesn't surface as a failure.
Do I need to refresh entitlement state manually after a purchase?
No. The receipt is validated server-side before awaitPurchase resumes, and the next awaitCustomerInfo() call reflects the new entitlement. Any UI bound to the customerInfo flow recomposes automatically.
Why does the SDK version include a plus sign?
The coordinate takes the form <sdk>+<hybrid-common>. The suffix matters when linking the iOS pod, so it should not be stripped.
What happens when appUserId is null?
The SDK generates an anonymous identifier in the form $RCAnonymousID:<uuid>. When the user later signs in to your backend, Purchases.sharedInstance.logIn(userId) transfers purchases to that account.
[versions]
purchases-kmp = "2.10.2+17.55.1"
[libraries]
purchases-kmp-core = { module = "com.revenuecat.purchases:purchases-kmp-core", version.ref = "purchases-kmp" }
purchases-kmp-ui = { module = "com.revenuecat.purchases:purchases-kmp-ui", version.ref = "purchases-kmp" }