Skip to content
AppDues
Log in
Contact salesSign up

Kotlin Multiplatform in-app purchases: how a purchases-kmp SDK is built

Kotlin Multiplatform lets one codebase run natively on Android, iOS and beyond, but the ecosystem long lacked a subscription layer. The purchases-kmp SDK fills that gap, and this guide walks through the architectural choices behind it, maps the modules it ships, and lists the concrete steps to wire it into a KMP app.

What Kotlin Multiplatform changes for billing code

Kotlin Multiplatform produces native binaries, which means Kotlin code occupies the same memory space as code written in each platform's primary language. No virtual machine sits in between and no bridging layer is needed, so platform APIs are callable directly. JetBrains has worked on the technology since 2017 and reached a first stable release in 2023; Google declared official support at Google I/O 2024, and a number of AndroidX libraries — Room, Paging, DataStore, and Compose with JetBrains' collaboration — already target it. The number of KMP libraries has roughly doubled over the past two years, so the ecosystem is expanding quickly, yet in-app purchase and subscription tooling has been a conspicuous gap. Without a shared SDK, teams end up hand-rolling wrappers around Apple's StoreKit and Google's Play Billing Library. A KMP subscription SDK aims to let you write that code once and cover both Android and iOS. Whether it is genuinely easier than working with StoreKit or Play Billing directly is a claim the SDK's publisher makes about its own product rather than an independently verified result, so treat it as a vendor assertion and evaluate it against your own integration. The library's history is likewise the publisher's own account: it reportedly began as an unofficial indie project called KobanKat and has since been developed to a stable v1 release.

Top-down or bottom-up: where the implementation lives

A bottom-up KMP design shares the lowest implementation layers across platforms. A top-down design shares only the public API and delegates implementation to the platform SDKs. The trade-off is real: bottom-up gives a thicker shared layer but requires re-implementing native edge-case handling; top-down keeps a thinner shared surface but inherits the years of nuance and bug fixes already baked into the platform SDKs. The KMP SDK was built top-down to stay consistent with the other cross-platform SDKs, and because KMP's flexibility means either approach is technically viable.

Type alias or wrapper: controlling the public surface

Once implementation lives in the platform SDKs, the shared layer has to decide how to expose it. KobanKat's early approach used expect classes with actual typealias on each platform — nearly zero runtime cost, but the platform SDK types bleed into the app's platform source sets. Code in androidMain, for instance, could import both the Android SDK and the KMP SDK types, which is confusing and effectively locks the design: removing those types later would break integrators.

The project moved to wrappers instead. The public API stays stable while the underlying implementation and architecture can evolve, which avoids breaking changes for integrators.

What ships in the purchases-kmp module set

The core artifact, purchases-kmp-core, carries the same subscription and in-app purchase logic as the other SDKs. purchases-kmp-ui adds Paywalls and Paywall footers via Compose Multiplatform, so a single call renders them on Android and iOS. Three optional add-ons extend convenience:

  • purchases-kmp-datetime adds extension properties that surface timestamps as kotlinx-datetime Instant values, useful if your project already depends on JetBrains' kotlinx-datetime for date handling.
  • purchases-kmp-result adds variants of every suspending function that return Kotlin's built-in Result type, for teams that prefer to avoid exceptions as control flow.
  • purchases-kmp-either does the same for Arrow's Either type, for teams using typed errors.

Pick the add-ons that match your existing error-handling style; none are required for core billing.

Integration checklist

  1. Declare the purchases-kmp libraries you need in your version catalog (libs.versions.toml).
  2. Opt in to ExperimentalForeignApi in your iOS source sets — the SDK uses generated Kotlin cinterop bindings for native iOS code.
  3. Link the PurchasesHybridCommon[UI] framework to your iOS project.
  4. Call Purchases.configure() to configure the SDK.
  5. Use Purchases.sharedInstance to reach the singleton that exposes all functionality.

The configure/sharedInstance pattern mirrors the other platform SDKs, so existing integrators will recognize it. Full installation details live in the official KMP installation docs.

Decision summary

DecisionChosenWhy
ArchitectureTop-downReuses mature platform SDK logic; avoids re-implementing edge cases
Shared API exposureWrappersKeeps public API stable; avoids leaking platform types into app source sets
PaywallsCompose Multiplatform via purchases-kmp-uiOne call renders on Android and iOS
Error handlingOptional Result / Either add-onsMatches existing Kotlin idioms without forcing them

Frequently asked questions

Why build a KMP SDK top-down instead of bottom-up?

Bottom-up shares the lowest implementation layers. Top-down shares only the public API and keeps implementation in the platform SDKs, which already handle years of edge cases and bug fixes. The KMP SDK was built top-down to stay consistent with the other cross-platform SDKs and to avoid rewriting that logic.

Why use wrappers instead of type aliases?

Type aliases have minimal runtime overhead but expose platform SDK types to the app's platform source sets, which is confusing and locks the design in place. Wrappers keep the public API stable so the implementation can change without breaking integrators.

Which purchases-kmp modules do I need?

purchases-kmp-core is required for subscription and in-app purchase logic. Add purchases-kmp-ui if you want Compose Multiplatform Paywalls. Add purchases-kmp-datetime, purchases-kmp-result, or purchases-kmp-either only if you want those specific conveniences.

What iOS-specific setup does the KMP SDK require?

Opt in to ExperimentalForeignApi in your iOS source sets, because the SDK uses generated Kotlin cinterop bindings for native iOS code, and link the PurchasesHybridCommon[UI] framework to your iOS project.

How do I start using the SDK after integration?

Call Purchases.configure() to configure the SDK, then use Purchases.sharedInstance to get the singleton that provides access to all functionality.