# 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 # Troubleshooting Common CLI errors and runtime surprises, what each one means and how to fix it. The most common failures, in two groups: errors the CLI prints, and runtime behavior that surprises people the first time. ## CLI errors ### `Not a superwall project` The CLI couldn't find a project from where you ran it. Run commands from your app root or from inside `superwall/`, and check that the project's `package.json` depends on `superwall`. See [Project structure](/docs/framework/project-structure). ### `…package.json is named "superwall"` Your project's `package.json` has `"name": "superwall"`, which shadows the framework import. Nothing in the project can `import` from `superwall` anymore. Rename the package; `superwall create` names it after your app for exactly this reason. ### `No superwall framework found` The project exists but its dependencies aren't installed, or `superwall` isn't among them. Run `bun add superwall` (or `npm install superwall`) inside the project directory. ### `This product / These N products do not exist on Superwall` A `config.ts` names a product identifier the dashboard has no product for. The push refuses because every variable on that product would be undefined on device. Either fix the identifier, or create the products, from the dashboard, or with `superwall products create` from the CLI. See [Products](/docs/framework/products) and the [CLI reference](/docs/framework/cli). ### `Superwall for Agents is in private beta and isn't enabled for this app yet` Pushing needs Superwall for Agents enabled on the Superwall app you're pushing to, per app, so a project on several platforms needs it on each one. Nothing in the CLI can turn it on; contact [support@superwall.com](mailto\:support@superwall.com) for access. ### `Multiple projects found. Pass --project .` Your account has several Superwall projects, and the command can't guess which one you mean. Add `--project ` (and usually `--app `) to the command. ### Diagnostics block the push Publishing is immutable, so a paywall with diagnostics, a stray non-page file in `app/`, a duplicate route, refuses to push. The message names each file and where it belongs. These are the same warnings `superwall dev` prints, so you'll usually have seen them before push time. A directory missing `app/index.tsx` or `config.ts` is the exception: it isn't a paywall yet, so push skips it silently instead of failing. If a paywall you expected didn't ship, check that both files exist. `superwall dev` lists what it found. ### Rename ambiguity in CI A renamed paywall directory can't be resolved interactively in CI, so the push stops rather than creating a duplicate. Add the `--rename old=new` flag the error prints. See [Push, promote & publish](/docs/framework/push-and-promote). ### `x doesn't say which platforms it's for` The project pushes to several platforms, and this paywall's `config.ts` has no `platforms` field. Add `platforms: ["ios", "android"]` (or whichever apply). A push never guesses which app a paywall belongs to. See [Configuration](/docs/framework/config#platforms). ### `` `annual` has no product id for web `` The paywall ships to a platform (here `web`) that its per-platform product slot doesn't name. Add an id for that platform (`annual: { ios: "…", android: "…", web: "…" }`) or remove the platform from `platforms`. See [Products](/docs/framework/products#one-reference-a-product-per-platform). ### `Several iOS apps in your account` / `no Web app to bind` A `config.ts` names a platform `superwall.lock` doesn't bind yet, and your account has either several apps of that platform or none. Run `superwall push` interactively once to choose, add `"web": ""` under `apps` in `superwall.lock` yourself (`superwall apps list --json` shows ids), or create the app (`superwall apps create --platform web`). See [Several platforms](/docs/framework/push-and-promote#several-platforms). ### `This project has no app for "…"` `--platform` takes `ios`, `android`, or `web`: one the project already binds in `superwall.lock` (or that app's id); the message lists the ones it has. ### `paywall x has never been pushed` (promote) Promote only moves the live pointer between pushed versions. There's nothing to point at yet. Push first. ### `superwall publish requires git` The source snapshot is part of every push, so `push` and `publish` both need git, the message names `publish` whichever you ran. Install git. ### `Pushing paywalls needs a Superwall account` Run `superwall login` once interactively, or set `SUPERWALL_API_KEY` (an `sk_…` key) in CI. `superwall dev` needs no login. ## Runtime surprises ### Prices are example values in dev The studio reads products from your dashboard when `superwall dev` is logged in. A slot the dashboard has no product for gets no variables, so prices render as whatever your own fallback shows — the studio will not stand in an invented price. Run `superwall login` if you haven't, then create the product on the dashboard or repoint the slot; push refuses until you do. Every read stays guarded and the unpriced state stays designed, because the SDK can still deliver a product before its data. The reading rules are in [Products](/docs/framework/products). ### A number comparison works in dev but not on device Numeric-looking variables are **strings on a real device** (`"59.99"`, `"7"`), while a dashboard sample in the studio may carry numbers. A `typeof x === "number"` check silently fails on every phone. Coerce with `Number()` before arithmetic or comparison ([Products](/docs/framework/products)). ### My entry animation already finished when the paywall appears The SDK preloads paywalls hidden, so components mount long before anyone is looking, a mount-timed animation plays to an empty room. Gate entry animations on presentation, not mount. See [Lifecycle & events](/docs/framework/lifecycle). ### Dark mode looks right on my machine, wrong on device The mechanism is the `dark` class the framework maintains on ``, not `prefers-color-scheme`. A media query can't see what the device reports and ignores the studio's theme toggle. Style off the class, as shown in [Styling](/docs/framework/styling). ### My `fetch` to my own API never arrives The server never saw it — the browser refused to send it. A published paywall runs under a Content-Security-Policy that permits Superwall and Stripe and nothing else, so a call to your own backend is blocked before any network activity: no DNS lookup, no request, nothing in your access logs. The only sign is a console error, `Refused to connect because it violates the document's Content Security Policy`, and the `fetch` promise rejecting with a bare `TypeError: Failed to fetch`. Name the host in `allowedHosts` and push again: ```ts title="superwall/funnels/onboarding/config.ts" export default definePaywall({ allowedHosts: ["api.example.com"], }); ``` Two things make this hard to spot. A rejected `fetch` looks exactly like a network failure, so a `catch` written for offline handling swallows it. And if the call only happens on a page shoppers reach near the end of a flow, nothing fails until then. See [Allowed hosts](/docs/framework/config#allowed-hosts). ### My link does nothing Inside a webview, an `` either does nothing or navigates the paywall away from itself. Open links through `useActions().openUrl` instead. See [Actions](/docs/framework/actions). ### Controls sit in the status bar / under the home indicator The paywall is inset from the edges by default, so this happens for one of two reasons: `insets` in `config.ts` turned that off for the edge in question, or the control is `position: fixed` and positioned from a bare `env()`, which is 0 in previews, in Android WebView and in some webview contexts. Fixed chrome positions from `var(--sw-safe-area-inset-top)` and friends: the safe area where the host reports one, a floor for the device and presentation where it doesn't. Chrome inside the layout should not be fixed at all. See [Insets](/docs/framework/styling#insets). ### The payment sheet doesn't open in dev By design. A preview has no API key, so a Stripe product resolves through the studio's purchase prompt instead of the payment sheet, which lets you test the flow and copy without creating checkout sessions. Push and open the live URL to verify the checkout itself. See [Web checkout](/docs/framework/web-checkout).