Skip to content
AppDues
Log in
Contact salesSign up

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.

Four shared concepts replace two store integrations

Without a shared SDK, each platform has its own product query, receipt format, verification API, and backend mapping. The KMP SDK collapses that into four objects your app reasons about:

  • Offerings: the set of products currently for sale, configured in the dashboard rather than in the app.
  • Packages: the buyable units inside an offering, such as monthly, annual, or lifetime.
  • Entitlements: access levels your app cares about, such as premium, pro, or family, independent of the store that processed payment.
  • CustomerInfo: one object aggregating every active entitlement for the current user.

With those in place, access checks stop asking which store the user paid through and start asking whether the premium entitlement is active. That check is identical on both platforms.

Dashboard prerequisites

Four things must exist before code:

  1. A project with one Android app and one iOS app, each linked to its store credentials.
  2. Products imported from Google Play Console and App Store Connect.
  3. An entitlement named premium (or an identifier of your choosing).
  4. 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.

CustomerInfo and EntitlementInfo fields used in this flow
FieldWhere it livesUse in this app
entitlements["premium"]CustomerInfoAccess gate; check isActive
isActiveEntitlementInfoThe only flag needed for gating
expirationDateEntitlementInfoDisplay of renewal timing
willRenewEntitlementInfoDisplay of renewal status
storeEntitlementInfoIdentify originating platform for display
activeSubscriptionsCustomerInfoSubscription management screen
originalAppUserIdCustomerInfoSubscription management screen

Field names and roles as described in the captured technical walkthrough; verify against the current SDK reference before shipping.

Module responsibilities in the reference project
ModuleResponsibilityPlatform-specific?
composeAppApp.kt, NavHost, Android Application init, iOS MainViewController bridgeYes (androidMain, iosMain)
feature/*Screens and ViewModels in Compose MultiplatformNo
core/dataPaywallsRepository; sole caller of Purchases.sharedInstanceNo
core/modelData classesNo
core/networkKtor clientNo
core/designsystemThemeNo
core/navigationNavigation graphNo

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" }