# 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

# PaywallOptions

Configuration for paywall presentation and behavior in the Superwall Android SDK.

> **Tip:** `PaywallOptions` is provided via the `paywalls` property on [`SuperwallOptions`](/docs/android/sdk-reference/SuperwallOptions) and is passed to the SDK when you call [`configure`](/docs/android/sdk-reference/configure).

## Purpose

Customize how paywalls look and behave, including preload behavior, alerts, dismissal, and haptics.

## Signature

```kotlin
import com.superwall.sdk.analytics.Tier
import kotlin.time.Duration

class PaywallOptions {
    var isHapticFeedbackEnabled: Boolean = true

    class RestoreFailed {
        var title: String = "No Subscription Found"
        var message: String = "We couldn't find an active subscription for your account."
        var closeButtonTitle: String = "Okay"
    }
    var restoreFailed: RestoreFailed = RestoreFailed()

    var shouldShowPurchaseFailureAlert: Boolean = true
    var shouldPreload: Boolean = true
    var preloadDeviceOverrides: Map<Tier, Boolean> = emptyMap()
    var useCachedTemplates: Boolean = false
    var automaticallyDismiss: Boolean = true

    enum class TransactionBackgroundView { SPINNER }
    var transactionBackgroundView: TransactionBackgroundView? = TransactionBackgroundView.SPINNER

    var overrideProductsByName: Map<String, String> = emptyMap()
    var loadingColor: Int? = null // @ColorRes
    var optimisticLoading: Boolean = false
    var timeoutAfter: Duration? = null
    var onBackPressed: ((PaywallInfo?) -> Boolean)? = null
}
```

## Parameters

<TypeTable
  type="{
  isHapticFeedbackEnabled: {
    type: &#x22;Boolean&#x22;,
    description: &#x22;Enables haptic feedback when users purchase/restore, open links, or close the paywall.&#x22;,
    default: &#x22;true&#x22;,
  },
  restoreFailed: {
    type: &#x22;RestoreFailed&#x22;,
    description: &#x22;Messaging for the restore-failed alert.&#x22;,
    required: true,
  },
  &#x22;restoreFailed.title&#x22;: {
    type: &#x22;String&#x22;,
    description: &#x22;Title for restore-failed alert.&#x22;,
    default: &#x22;No Subscription Found&#x22;,
  },
  &#x22;restoreFailed.message&#x22;: {
    type: &#x22;String&#x22;,
    description: &#x22;Message for restore-failed alert.&#x22;,
    default: &#x22;We couldn't find an active subscription for your account.&#x22;,
  },
  &#x22;restoreFailed.closeButtonTitle&#x22;: {
    type: &#x22;String&#x22;,
    description: &#x22;Close button title for restore-failed alert.&#x22;,
    default: &#x22;Okay&#x22;,
  },
  shouldShowPurchaseFailureAlert: {
    type: &#x22;Boolean&#x22;,
    description: &#x22;Shows an alert after a purchase fails. Set to `false` if you handle failures via a `PurchaseController`.&#x22;,
    default: &#x22;true&#x22;,
  },
  shouldPreload: {
    type: &#x22;Boolean&#x22;,
    description: &#x22;Preloads and caches trigger paywalls and products during SDK initialization. Set to `false` for just-in-time loading.&#x22;,
    default: &#x22;true&#x22;,
  },
  preloadDeviceOverrides: {
    type: &#x22;Map<Tier, Boolean>&#x22;,
    description: &#x22;Overrides `shouldPreload` for specific device tiers. Any tier not listed here falls back to `shouldPreload`.&#x22;,
    default: &#x22;emptyMap()&#x22;,
  },
  useCachedTemplates: {
    type: &#x22;Boolean&#x22;,
    description: &#x22;Loads paywall template websites from disk when available.&#x22;,
    default: &#x22;false&#x22;,
  },
  automaticallyDismiss: {
    type: &#x22;Boolean&#x22;,
    description: &#x22;Automatically dismisses the paywall on successful purchase or restore.&#x22;,
    default: &#x22;true&#x22;,
  },
  transactionBackgroundView: {
    type: &#x22;TransactionBackgroundView?&#x22;,
    description: &#x22;View shown behind the system payment sheet during a transaction. Use `null` for no view.&#x22;,
    default: &#x22;.SPINNER&#x22;,
  },
  overrideProductsByName: {
    type: &#x22;Map<String, String>&#x22;,
    description: &#x22;Overrides products on all paywalls using name\u2192identifier mapping (e.g., `\&#x22;primary\&#x22;` \u2192 `\&#x22;com.example.premium_monthly\&#x22;`).&#x22;,
    required: true,
  },
  loadingColor: {
    type: &#x22;Int?&#x22;,
    description: &#x22;A `@ColorRes` used to tint the spinner shown while a purchase or restoration is in progress. Only applies to the SDK's built-in loading view; style a custom `PaywallBuilder.purchaseLoadingView` directly instead.&#x22;,
    default: &#x22;null&#x22;,
  },
  optimisticLoading: {
    type: &#x22;Boolean&#x22;,
    description: &#x22;Hides shimmer optimistically.&#x22;,
    default: &#x22;false&#x22;,
  },
  timeoutAfter: {
    type: &#x22;Duration?&#x22;,
    description: &#x22;Duration until a paywall timeout is invoked. When not using fallback loading, setting this triggers a timeout instead of retrying.&#x22;,
  },
  onBackPressed: {
    type: &#x22;((PaywallInfo?) -> Boolean)?&#x22;,
    description: &#x22;Callback invoked when back button is pressed (requires `reroute_back_button` enabled in paywall settings). Return `true` to consume the back press, `false` to use SDK default behavior.&#x22;,
    default: &#x22;null&#x22;,
  },
}"
/>

## Usage

```kotlin
val paywallOptions = PaywallOptions().apply {
    isHapticFeedbackEnabled = true
    shouldShowPurchaseFailureAlert = false
    shouldPreload = true
    preloadDeviceOverrides = mapOf(
        Tier.ULTRA_LOW to false,
        Tier.LOW to false,
    )
    useCachedTemplates = false
    automaticallyDismiss = true
    transactionBackgroundView = PaywallOptions.TransactionBackgroundView.SPINNER
    overrideProductsByName = mapOf(
        "primary" to "com.example.premium_monthly",
        "tertiary" to "com.example.premium_annual",
    )
    loadingColor = R.color.brand_purple
    optimisticLoading = false
    timeoutAfter = null
    onBackPressed = { paywallInfo ->
        // Custom back button handling
        // Return true to consume the back press, false to use SDK default
        false
    }
}

val options = SuperwallOptions().apply {
    paywalls = paywallOptions
}

Superwall.configure(
    application = this,
    apiKey = "pk_your_api_key",
    options = options,
)
```

`preloadDeviceOverrides` is useful when you want to keep preloading enabled by default but disable it on lower-end devices. Tiers you do not specify continue to use the `shouldPreload` value.

## Related

* [`SuperwallOptions`](/docs/android/sdk-reference/SuperwallOptions)