# 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

# Superwall Framework

Build paywalls, onboarding funnels, and web checkout flows as React mini-apps — in your repo, with your tools, shipped without an app update.

The Superwall Framework lets you build paywalls, onboarding funnels, and web checkout flows as code. Each one is a small React app in a `superwall/` directory inside your repo: a `config.ts` that declares its name and products, an `app/` directory of pages, and whatever components, styles, and assets it needs. Superwall provides everything else — products, purchases, localization, trial handling, and the bridge to the native SDKs — so you never touch native code to change what your users see.

```ts
superwall/paywalls/pro/
├── config.ts          definePaywall({ name, products: { annual: "pro_5999_year" } })
├── app/               pages — index.tsx, plans.tsx, layout.tsx
├── components/        everything that is not a page
└── messages/en.ts     localized strings, discovered by filename
```

You preview locally with `superwall dev`, which opens a studio with device frames, light/dark toggles, locale switching, and simulated purchases. When you're happy, `superwall push` seals an immutable version, and `superwall promote` points production at it — your users get the new paywall on the next open, no app review required.

> **Note:** The framework requires the **headless paywalls** feature to be enabled on your Superwall application. If a push tells you it isn't, contact us to have it turned on.

## Why code-first?

* **It's just React.** State, components, hooks, CSS — nothing to relearn, and your existing component patterns carry over. Use Tailwind, Motion, Rive, or plain CSS; the framework doesn't care.
* **Version-controlled and reviewable.** Paywalls live in your repo, go through your PR process, and ship from CI if you want them to.
* **Ship without app releases.** Pushed paywalls are delivered remotely by the same SDKs you already use. Promote a new version — or roll back — in seconds.
* **Store data stays store-owned.** Prices, periods, and trials come from the App Store, Google Play, or Stripe at runtime, localized and formatted for each user. You never hardcode a price.
* **One flow, many steps.** Multi-page onboardings and funnels are a single paywall whose steps are pages on a navigation stack — no network between steps, no loading spinners.

## How it fits together

| Piece             | What it does                                                                       |
| ----------------- | ---------------------------------------------------------------------------------- |
| `superwall` (npm) | The framework: `definePaywall`, hooks, navigation, the build                       |
| `superwall` (CLI) | `create`, `dev`, `push`, `promote`, `publish`                                      |
| The studio        | Local preview at `localhost:6100` — devices, themes, locales, simulated outcomes   |
| The dashboard     | Where pushed paywalls, versions, and products live; campaigns decide who sees what |
| The native SDKs   | Present your paywall in-app, deliver product data, run purchases                   |

Your app keeps presenting paywalls exactly as it does today — through placements and campaigns. The framework changes how paywalls are *built*, not how they're *shown*.

## Start here

## Quickstart

/docs/framework/quickstart

Scaffold a project, preview your first paywall in the studio, and ship it.

## Project structure

/docs/framework/project-structure

How a `superwall/` directory is laid out and which files to commit.

## Pages & navigation

/docs/framework/navigation

Build multi-page flows with file-based routes and a stack router.

## Purchases

/docs/framework/purchases

Declare products, read live prices, and handle every purchase outcome.

## Go deeper

* **[Configuration](/docs/framework/config)** — everything `definePaywall` accepts, from presentation style to trial reminders.
* **[Web checkout](/docs/framework/web-checkout)** — sell the same paywall on the web with one config key.
* **[Variables & personalization](/docs/framework/variables)** — react to user attributes, device state, and placement parameters.
* **[Localization](/docs/framework/localization)** — one file per locale, picked automatically from the device.
* **[Examples](/docs/framework/examples)** — complete standalone projects, each teaching one idea.