# Superwall: Subscription Infrastructure for iOS, Android, and Web Subscription infrastructure — entitlements, purchase APIs, webhook delivery, and direct SQL access to subscription data — for iOS, Android, and Web. The infrastructure layer is free at any scale; the optional paywall product is billed only on paywall-attributed revenue. ## Pricing - **Infrastructure: free at any scale, every plan.** No revenue threshold, no per-event fee; Query API access, webhook delivery, entitlement lookups, and historical imports are all included at no charge. - **Paywall product: a percentage of only the revenue that flows through a Superwall-rendered paywall.** Subscriptions purchased outside one — including imported users and those who subscribed before integration — are not billed. Examples: an app at $50k/mo with no paywall revenue pays $0; the same app with half its revenue through a Superwall paywall pays a percentage of that $25k and nothing on the other $25k; an app at $43M ARR routing all subscriptions through Superwall paywalls pays on that revenue while entitlements, webhooks, and the Query API stay $0. ## Scale $1.5B+ annual subscription revenue across 10,000+ apps. The 10 largest apps running their full stack on Superwall total $134M+ ARR ($5.7M–$43.7M each). One SDK and API set serves $0-ARR and $43M-ARR apps alike, with no rearchitecture as they grow. ## Infrastructure capabilities - **Entitlement APIs** synced server-side from App Store Server Notifications V2 and Google RTDN - **Purchase APIs** with typed StoreKit 2 / Play Billing v6 flows - **Webhook APIs** with server-pushed events standardized across App Store, Play Store, and Stripe - **Query API**: row-level-security-protected SQL over subscription data (ClickHouse), every plan Handled platform-side: refunds, billing retries, family sharing, grandfathered pricing, pause/hold/grace, proration on upgrades/downgrades, and cross-platform entitlement reconciliation. ## Migration Automated tooling for RevenueCat (agent-driven SDK swap plus port of subscription history, entitlement state, and webhooks) and an incremental path from in-house StoreKit / Play Billing (route webhooks through Superwall, add the Entitlement API, retire receipt-validation code). ## Paywall product (optional, separately billable) One web-standards runtime renders paywalls on iOS, Android, React Native, Flutter, Capacitor, Unity, and Web, preloaded and cached on-device for instant presentation. Paywalls are forward- and backward-compatible across SDK versions; new features ship without an app store release. ## Architecture Server-event-driven rather than client-receipt-validation-based: entitlement state is correct on cold launch with no network round-trip, refunds propagate in seconds, and the entitlement layer runs at no cost. ## Docs * Migrate from RevenueCat: https://superwall.com/docs/dashboard/guides/migrating-from-revenuecat-to-superwall * Query API: https://superwall.com/docs/dashboard/guides/query-clickhouse * Webhooks: https://superwall.com/docs/integrations/webhooks * Pricing: https://superwall.com/pricing # Tracking Subscription State Observe whether a user is on a paid plan from shared Kotlin code. > **Warning:** **Beta**The KMP SDK is in beta and its API may change between releases. Superwall tracks subscription state for you. But there are times you need to know directly whether a user is on a paid plan, either to show different UI or to unlock something without a placement. ## Read it synchronously ```kotlin import com.superwall.sdk.kmp.models.entitlements.SubscriptionStatus when (val status = Superwall.subscriptionStatus) { is SubscriptionStatus.Active -> showPro(status.entitlements) is SubscriptionStatus.Inactive -> showFree() is SubscriptionStatus.Unknown -> showLoading() } ``` `SubscriptionStatus` has three states: | State | Meaning | | -------------------------- | ------------------------------------------------------------ | | `Unknown` | Not yet determined, typically before configuration completes | | `Active(Set)` | The user has one or more active entitlements | | `Inactive` | The user has no active entitlements | There is also a convenience boolean: ```kotlin if (Superwall.subscriptionStatus.isActive) { /* ... */ } ``` > **Warning:** Treat `Unknown` as its own case, not as "not subscribed". Showing free-tier UI during `Unknown` > will flash the wrong state at paying users on cold start. ## Observe changes `subscriptionStatusFlow` is a `StateFlow`, so it always has a current value and emits on change: ```kotlin import kotlinx.coroutines.launch scope.launch { Superwall.subscriptionStatusFlow.collect { status -> when (status) { is SubscriptionStatus.Active -> showPro(status.entitlements) is SubscriptionStatus.Inactive -> showFree() is SubscriptionStatus.Unknown -> showLoading() } } } ``` > **Note:** **Two naming details to watch for if you are coming from the Android SDK.**The flow is `Superwall.subscriptionStatusFlow`. The plain `Superwall.subscriptionStatus` is a synchronous property, not a flow. On the Android SDK, `subscriptionStatus` *is* the flow\.And this flow is **guard-exempt**: you can collect it before `configure`, where it is seeded with `SubscriptionStatus.Unknown` and attached to the native source once configuration completes. You do not have to sequence collection behind configuration. > **Warning:** This is a plain `StateFlow`, which means it delivers on **your collector's context** and does not force emissions onto the main thread. Collect it from a main-dispatched scope (`collectAsState`, `viewModelScope`, `lifecycleScope`) and updating UI from the collector is safe. Collect it on `Dispatchers.IO` and it is not.The SDK's own KDoc says emissions arrive on the main thread; that is true of the common case, not a guarantee the flow enforces. ### With Compose Multiplatform ```kotlin @Composable fun ContentScreen() { val status by Superwall.subscriptionStatusFlow.collectAsState() when (val current = status) { is SubscriptionStatus.Active -> PremiumContent(current.entitlements) is SubscriptionStatus.Inactive -> FreeContent() is SubscriptionStatus.Unknown -> LoadingIndicator() } } ``` ## Setting it yourself If you configured with a [`PurchaseController`](/docs/kmp/guides/advanced-configuration), you own subscription state and must set it: ```kotlin Superwall.subscriptionStatus = SubscriptionStatus.Active(entitlements) ``` > **Note:** Only set this when you have a `PurchaseController`. Without one, Superwall manages the value and > writing to it will fight the SDK. ## Detailed purchase history `CustomerInfo` carries more than `SubscriptionStatus` does, including full transaction history that merges device and web purchases: ```kotlin val info = Superwall.getCustomerInfo() info.subscriptions // List info.nonSubscriptions // List info.entitlements // List info.userId // String ``` Each `SubscriptionTransaction` includes `productId`, `purchaseDate`, `expirationDate`, `willRenew`, `isActive`, `isInGracePeriod`, and more. Observe changes with `customerInfoFlow`: ```kotlin scope.launch { Superwall.customerInfoFlow.collect { info -> render(info) } } ``` > **Note:** Customer info works on **both** platforms. If you are reading the SDK's own KDoc, note that the > `@platform iOS` annotations on `customerInfoFlow` and `getCustomerInfo` are out of date. They > describe a limitation that no longer applies. On Android the flow is fed by the native > `customerInfoDidChange` delegate hook, and `getCustomerInfo()` calls straight through to > `superwall-android` 2.8.0. > **Note:** `customerInfoFlow` has no replay, so a new collector gets nothing until the next change. Use > `getCustomerInfo()` for the current value. ## Restoring purchases ```kotlin import com.superwall.sdk.kmp.models.results.RestorationResult when (val result = Superwall.restorePurchases()) { is RestorationResult.Restored -> println("Restored") is RestorationResult.Failed -> println("Restore failed: ${result.error}") } ``` Restoration failure stays in the return type and does not throw. `Restored` means the restore completed without errors, not that the user necessarily has an active subscription.