# 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 # Configuration Everything definePaywall accepts, products, background, transitions, trial reminders, and the behavior settings that shape a paywall. Every paywall declares itself in a required `config.ts`: its dashboard name, its products, and any behavior settings. This file is the whole truth for the paywall. Nothing is inherited from anywhere else. ```ts import { definePaywall } from "superwall/config"; export default definePaywall({ name: "Plus — Annual, 3-day trial", products: { monthly: "pro_999_month", annual: "pro_5999_year", }, }); ``` TypeScript is the only validation, so keep the object literal inline. That's what lets the compiler catch typos. If you want to share settings between paywalls, export a plain object and spread it: ```ts // superwall/components/shared-config.ts export const shared = { transition: "slide", background: "#0d0f12" } as const; // paywalls/pro/config.ts export default definePaywall({ ...shared, name: "Pro", products: { … } }); ``` ## Options | Key | Type | Default | What it does | | ------------------------------ | ------------------------------------------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | `string` | directory name, title-cased | The label shown in the dashboard. The directory stays the identifier. | | `platforms` | `("ios" \| "android" \| "web")[]` | the project's only platform | Which platforms this paywall is pushed to, see [below](#platforms). Required once the project pushes to several. | | `products` | `Record` | — | Product slots by reference, optionally one id per platform, see [below](#products). | | `transition` | `"push" \| "slide" \| "fade" \| "shift" \| "none"` or custom | `"push"` | Default page transition, see [Transitions](/docs/framework/transitions). | | `queryState` | `boolean` | on when `checkout` is set | Keep the route stack and every `useQueryState` value in the page URL, so the flow resumes from any link. Never applies on a native host, see [Pages & navigation](/docs/framework/navigation). | | `checkout` | mode or `{ mode, prefetch?, managedPayments? }` | — | Sell on the web. Omit for native-only, see [Web checkout](/docs/framework/web-checkout). | | `background` | `string` or `{ light, dark? }` | — | Background color painted behind the paywall while it loads and as the page background, see [below](#background). | | `presentation` | `{ style, drawer?, popup? }` | `{ style: "fullscreen" }` | How the SDK presents the paywall, see [below](#presentation). | | `insets` | `"safe-area" \| "none" \| number \| string \| { top?, right?, bottom?, left? }` | `"safe-area"` | What the paywall is padded with at each screen edge, see [below](#insets). | | `featureGating` | `"gated" \| "nonGated"` | `"nonGated"` | Whether the feature behind the placement is gated on a purchase. | | `onDeviceCacheEnabled` | `boolean` | `true` | Cache the paywall on device for instant presentation. | | `gameControllerEnabled` | `boolean` | `false` | Forward game controller input to the paywall. | | `introductoryOfferEligibility` | `"automatic" \| "eligible" \| "ineligible"` | `"automatic"` | How the SDK decides trial eligibility for this paywall's products. `"automatic"` asks the store; the other two force the answer, useful to preview or ship one variant regardless of the shopper's history. Native only: on the web a trial is whatever the Stripe price's offer says. See [Trials](/docs/framework/trials). | | `postPurchase` | `"dismiss" \| "stay" \| "redeem" \| { redirect }` | `"dismiss"` | What happens once a purchase completes. `"redeem"` and `{ redirect }` are web-only. See [below](#post-purchase). A `purchase()` call can override it per button. | | `notifications` | `{ trialReminder }` | — | Trial-reminder notification, see [below](#trial-reminder-notifications). | | `localization` | `{ defaultLocale, messages? }` | `"en"` | Fallback locale; file-based catalogs need no config, see [Localization](/docs/framework/localization). | | `scrollEnabled` | `boolean` | `true` | Whether the paywall scrolls. | | `allowedHosts` | `string[]` | — | Hosts this surface may call over the network, as bare hostnames. Superwall and Stripe are always reachable; anything else is refused until it is named here, see [below](#allowed-hosts). | > **Note:** A paywall built with the framework has no dashboard editor, so `config.ts` is the only place its settings live. Presentation, feature gating, caching, scrolling, game controller, web checkout destination, and background all travel with the pushed version and are applied on promote, which also means `promote --version` rolls them back with the code. Whatever a config omits resets to the default in the table. > **Note:** There is deliberately **no identifier field**. The directory path is the paywall's identity, and the dashboard binding lives in `superwall.lock`, never in this file. See [Project structure](/docs/framework/project-structure). ## Allowed hosts A published paywall runs under a Content-Security-Policy Superwall enforces when it serves the page. By default it may talk to Superwall and Stripe and nothing else, so a `fetch` to your own API is refused by the browser before it reaches the network — no request is sent, and the only sign is a CSP error in the console. Name the hosts you call and they are permitted: ```ts title="superwall/funnels/onboarding/config.ts" export default definePaywall({ name: "Onboarding", allowedHosts: ["api.example.com"], }); ``` Write bare hostnames — `https` is implied and required. A pasted `https://api.example.com` is accepted and normalizes to the same thing. An explicit port is kept (`api.example.com:8443`). Not accepted: `http://`, wildcards like `*.example.com`, paths, and anything that is not a hostname. Every entry is https, with no exception — a served policy should never be able to carry a plaintext origin. Each one goes into that policy verbatim, so it has to be a host you actually call rather than a pattern. `superwall push` fails and names the entry it could not read, so a typo stops the push instead of becoming a blocked request in production. ### A local API You do not need to name one. **`superwall dev` applies no policy at all**, so a `fetch` to `http://localhost:3000` works there whether or not it appears in `allowedHosts`. `localhost` and `127.0.0.1` are rejected outright, and the push says so. The reason is arithmetic rather than policy: a pushed paywall runs on a shopper's device, where `localhost` is *their* machine, not yours — so the entry could only widen the policy for everyone in exchange for a request that cannot succeed. To reach a local API from a **pushed** build, put it behind an https tunnel (ngrok, cloudflared) and name that hostname. > **Note:** The flip side is that a missing host never fails in dev, only after deploy. Add the host in the same change that writes the `fetch`, not when you notice it failing. > **Note:** A surface may name up to 20 hosts. If you need more, the work usually belongs behind one backend of your own — and every entry widens the policy for every shopper who sees the paywall. The list travels with the pushed version, like every other setting here, so `promote --version` rolls it back with the code and two versions can permit different hosts. > **Callout:** This is not a formality. The policy also permits `unsafe-eval`, which the bundler output needs, so the set of reachable hosts is what keeps a published paywall from fetching and running code nobody reviewed. Name the host you call, not a wildcard that happens to cover it. ## Post-purchase `postPurchase` is one setting for both platforms; each host reads the part it can act on. | Value | Native | Web | | --------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `"dismiss"` (default) | SDK dismisses the paywall. | The host does what the placement says: grant access and close in a Web SDK overlay, redeem on a hosted page. | | `"stay"` | Nothing is dismissed. | The paywall keeps control; finish the purchase with [`useCheckoutRedemption()`](/docs/framework/hooks#usecheckoutredemption) — a success screen, a "Continue to app" button. | | `"redeem"` | Same as `"dismiss"`. | Send the shopper to the redemption page, which opens the app with their code. | | `{ redirect: url }` | Same as `"dismiss"`. | Send the shopper to `url` with their redemption code attached. | Without a `checkout`, or with `platforms` that leave out `"web"`, the type narrows to `"dismiss" | "stay"` — there is nowhere to redeem or redirect to. A `purchase(ref, { postPurchase })` call overrides it for that button. ## Platforms A project can push to several platforms: an iOS app, its Android counterpart, and a web app, all in the same Superwall project. `platforms` says which of them this paywall is for: ```ts // paywalls/plus-upgrade/config.ts: one directory, shipped to both stores export default definePaywall({ platforms: ["ios", "android"], products: { … } }); // paywalls/web-upgrade/config.ts: the web app only export default definePaywall({ platforms: ["web"], checkout: "sheet", products: { … } }); ``` The values are `ios`, `android`, and `web`, and the array is typed, so anything else is a compile error. The project binds one Superwall app per platform in `superwall.lock`, and every platform listed gets its own dashboard paywall, pushed and promoted independently: a shared directory is one codebase with one live version per platform. On a single platform the field is optional. Once the project pushes to more than one, every paywall has to say; a push refuses a silent one rather than guess. There is no project-wide default on purpose (`config.ts` is the whole truth for its paywall); to mirror a set everywhere, share it like any other setting, `export const everywhere = { platforms: ["ios", "android", "web"] } as const`, and spread it. A reference stays the same on every platform, but the store product behind it usually doesn't. Give such a slot one id per platform (`annual: { ios: "…", android: "…" }`, [below](#products)); each platform's build and version carry their own. Binding a platform to an actual app happens on the first push, see [Push, promote & publish](/docs/framework/push-and-promote#several-platforms). ## Presentation How the native SDK shows the paywall. `style` is one of `fullscreen` (default), `modal`, `push`, `noAnimation`, `drawer`, or `popup`; the last two take geometry, as percentages of the screen and a corner radius in points: ```ts presentation: { style: "drawer", drawer: { height: 60, cornerRadius: 24 } } presentation: { style: "popup", popup: { width: 80, height: 60, cornerRadius: 15 } } ``` Geometry is optional and defaults to a 70% drawer or an 80% × 60% popup with a 15pt radius, the same defaults the editor uses. A zero or negative dimension fails the build. Web builds ignore presentation; the browser is the page. The style also shapes the paywall's [insets](#insets): a modal or drawer starts below the status bar, so the top inset is 0 there, and a popup is inset by the SDK on every side. The style is stamped on `` as `data-sw-presentation` for CSS that wants to know. ## Insets What the paywall is padded with at each screen edge. The default, `"safe-area"`, keeps every layout and page clear of the status bar, cutout and home indicator on the device the paywall is running on, and clear of nothing on the web: ```ts insets: "safe-area" // default — the device's safe area, floored per platform and presentation insets: "none" // flush to every edge: a full-bleed paywall insets: 24 // pixels, all four edges insets: "1.5rem" // any CSS length insets: { top: "none", bottom: "safe-area" } // per edge; an omitted edge stays "safe-area" ``` Insets never shrink the scroll area: each page scrolls edge to edge and carries the inset as its scroll padding, so content passes under the bars and rests clear of them. Turn an edge off only for something that must rest under the bar. A full-bleed design (`"none"`, or `top: "none"` for a hero whose top edge is the screen edge) keeps its close button out of the bar with `--sw-safe-area-inset-top`, which the framework maintains whatever `insets` says. How the safe area is resolved, and the variables behind it, are in [Styling](/docs/framework/styling#insets). Insets are a page-level concern and are not part of the version's settings; the SDK is not involved. ## Background Set the color that sits behind the paywall. The string shorthand sets it for light mode; the object form adds a dark-mode color: ```ts background: "#0d0f12" // or background: { light: "#ffffff", dark: "#0d0f12" } ``` Colors are 6- or 8-digit hex (`#RRGGBB` or `#RRGGBBAA`). Shorthand like `#fff`, named colors, and `rgb()` are rejected at push. It does two things from one value: native SDKs paint it behind the webview and derive the loading spinner from it, and the web document uses it as the page background, so the color a shopper sees while the paywall loads matches the color it settles on. It takes effect on the next `superwall publish`; when absent, paywalls fall back to the platform default. ## Products Products are **slots**. The key is the reference your code uses; the value is the store identifier: ```ts products: { annual: "pro_5999_year", // shorthand monthly: { productId: "pro_999_month" }, // same thing yearly: { ios: "pro_5999_year", android: "pro_5999_year_play" }, // one id per platform } ``` A per-platform slot must name every platform in `platforms`; a push refuses one that can't resolve on a platform it ships to. Your components read them by reference (`getProduct("annual")`, `purchase("annual")`), and the references are typed, so a typo is a compile error. Web/Stripe products put the Stripe price inside the identifier using the `{test|live}:price_…:{offer}` format. Product **data** (price, period, trial) never appears in this file. It's store-owned and arrives at runtime; a reference the dashboard has no product for renders undefined variables and blocks publishing. The full story, including how to read product variables safely, is in [Products](/docs/framework/products). ## Trial reminder notifications Declare a local notification and the SDK schedules it when a trial actually starts. The paywall doesn't need to be open when it fires: ```ts notifications: { trialReminder: { title: "Your trial ends tomorrow", body: "Keep Pro, or cancel in Settings — no charge either way.", beforeTrialEndDays: 1, // default 1 }, }, ``` `title`, `subtitle`, and `body` accept message keys (resolved through `t()`) or literal copy. For full control, pass a function instead. It receives `{ trialEndDate, product, t, locale }` and returns `{ title, body, delayMs }`, or `null` to skip the notification entirely. The trial reminders example shows both forms, see [Examples](/docs/framework/examples). ## Experimenting without rebuilds Variables are never declared in this file: everything the paywall reads (`useVariables()`, product variables, trial eligibility) is supplied by your app and the store at runtime, and the studio can override all of it live while you preview. Write your paywall to read variables defensively and every one of them becomes experimentable from the dashboard, no rebuild required. See [Variables & personalization](/docs/framework/variables).