# 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 # Using Referral or Promo Codes with Superwall Run referral and promo code offers with Superwall: validate codes in your app and show a discounted paywall, or use Stripe promotion codes on web checkout. > **Note:** For which store discount codes Superwall can apply, such as App Store offer codes or Google Play promo codes, see [Offer Codes, Promo Codes and Discounts](/docs/dashboard/guides/offer-codes-and-promo-codes). There are two primary ways to use referral codes or promo codes with Superwall: 1. **Using Superwall's Mobile SDKs**: By using [custom actions](/docs/sdk/guides/advanced/custom-paywall-actions) along with a [campaign](/docs/dashboard/dashboard-campaigns/campaigns) for referrals, you can create a flow to handle referral codes and see their resulting conversions and other data. You create the products that each referral should unlock within the respective app storefront. 2. **Web Checkout**: For Stripe products, add an **Apply Discount** button to the paywall. Users enter a Stripe promotion code, and Superwall validates it and applies it at checkout. See [Discount Codes](/docs/web-checkout/web-checkout-discount-codes). You can also create a [checkout link](/docs/web-checkout/web-checkout-creating-campaigns-to-show-paywalls) for each referral that leads to a paywall with a discounted Stripe product. ### Understanding Superwall's role Before you continue, it's critical to understand Superwall's role in this process. Most referral flows usually call for two things: 1. A way to enter in a referral code and validate it. 2. And, a resulting discounted offer that the user can redeem. **For App Store and Google Play products, your app validates the code.** Superwall can't apply a store's own discount codes from a paywall, so you create the discounted products in App Store Connect or Google Play Console, and Superwall shows them on a paywall once your app accepts the code. For Stripe products, Superwall validates Stripe promotion codes itself with **Apply Discount**, and you don't need separate discounted products. You can collect the code on the paywall itself instead of in your own screen: add a text input and a button with a **Custom Callback** action that sends the input's value to your app. Your app validates it and returns success or failure, and the paywall runs its **onSuccess** or **onFailure** actions. See [Custom callbacks](/docs/ios/guides/advanced/custom-callbacks). The steps below show the other way, with your own referral screen. ### Referral flows Given that information, here is how most referral flows can work: ## Tab ```mermaid {`flowchart TD A([Paywall is shown]) --> B[Referral Code claim\\nbutton is tapped] B --> C[Custom Action is fired\\nfrom button tap] C --> D[Responding in your Superwall Delegate,\\nyou present your own referral UI\\non top of the existing paywall] D --> E{Code is valid?} E -- NO --> F[Dismiss referral UI,\\nexisting paywall is still presented] E -- YES --> G[Dismiss referral UI,\\ndismiss existing paywall.\\nRegister placement for the referral code.] G --> H[Present new paywall with discounted product.\\nIn Superwall, you can use campaign data\\nto attribute conversions, trials, etc.] `} ``` Now, let's go through each step in detail. We'll assume that you're triggering this flow from a paywall that's already presented, but if that's not the case — just skip to the step where you present your referral entry UI (step four):## Create a new campaign for your referrals. Create a campaign for your referrals. Here, you'd add the discounted product(s) you've made to a paywall. You can add in as many placements as you need. Maybe there's one for each influencer, or seasonal discount offer, etc. You'll register one of these placements later on if the referral code entry was successful. ## Referral code is tapped. A paywall is shown. On it, this button that reads "Referral Code" has a custom tap action called "showPromoRedeem" which gets tapped: ![](https://superwall.com/docs/images/rc_1.jpg) ## SuperwallDelegate handles custom action This app has a [`SuperwallDelegate`](/docs/sdk/guides/using-superwall-delegate):```swift @main struct Caffeine_PalApp: App { @State private var delegate: SWDelegate = .init() init() { Superwall.configure(apiKey: "api_key") // Delegate configured here Superwall.shared.delegate = delegate } var body: some Scene { WindowGroup { ContentView() } } } ```Using the [`SuperwallDelegate`](/docs/sdk/guides/using-superwall-delegate), the app responds to the custom action. It presents a customized referral redemption interface *on top* of the existing paywall. This is optional, but presenting over the paywall means that the user will be taken back to it if the redemption code entry fails:> **Note:** Presenting custom UI on top of an existing paywall is only supported in the native iOS and Android SDKs. ```swift @Observable class SWDelegate: SuperwallDelegate { enum CustomActions: String, Identifiable { case showPromoRedeem var id: Self { self } } func handleCustomPaywallAction(withName name: String) { guard let action: CustomActions = .init(rawValue: name) else { print("Unexpected custom action: \(name)") return } switch action { case .showPromoRedeem: let referralUI = UIHostingController(rootView: ReferralRedeemView(callback: { // TODO: Implement placement on success })) if let paywallVC = Superwall.shared.presentedViewController { paywallVC.present(referralUI, animated: true) } else { // Present either using SwiftUI .sheet or other means } } } } ``` ## Referral UI is shown. Now that your referral interface is showing, you'd validate the code on your server or by some other means. ![](https://superwall.com/docs/images/rc_2.jpg) ## If it's successful, register a placement for referrals Now, if the code succeeds, you'd dismiss the referral UI and the existing paywall. In our callback, we...1) Dismiss the existing views. 2) And, we register a placement that corresponds to a campaign you've setup for referral codes:```swift // This... let referralUI = UIHostingController(rootView: ReferralRedeemView(callback: { // TODO: Implement placement on success })) // Might look similar to this... let referralUI = UIHostingController(rootView: ReferralRedeemView(callback: { // Dismiss the referral UI referralUI.dismiss(animated: true) // Dismiss the existing paywall Superwall.shared.presentedViewController?.dismiss(animated: true) // This shows the paywall with the discounted product. // It should be gated, which means the closure only fires if they convert. Superwall.shared.register(placement: "referral", params: ["influencer":"Jordan"]) { MyAnalyticsService.shared.log("referral_code_redeemed", properties: ["referral_code": "Jordan", "result": "trial_started"]) } })) ``` ## The discounted product is presented. Finally, your paywall and discounted product that you setup in step #1 is shown. If they convert, you'll see all of the details in your campaign that you built for referrals, just like you would any other campaign. You can also forward events to your third party analytics service as well, as shown in the previous step. ![](https://superwall.com/docs/images/rc_3.jpg) And that's it! It's a matter of creating discounted products, using them in a campaign, showing a referral UI and validating it, and then registering a placement to show those paywalls within a campaign. ## Tab > **Tip:** To use one paywall for every code, add an **Apply Discount** button and create promotion codes in Stripe. See [Discount Codes](/docs/web-checkout/web-checkout-discount-codes). The steps below use a separate discounted product per referral instead. The flow on web checkout is considerably easier, and that's primarily because you aren't navigating app storefronts for products and have a direct link to payments. And, just like with mobile, you can use your own referral entry system if you've got one to reveal web checkout links and their paywalls. Here's how it works:## Create a new campaign for your referrals. Create a campaign for your referrals. Here, you'd add the discounted product(s) you've made to a paywall that were created in Stripe. You can add in as many placements as you need. Maybe there's one for each influencer, or seasonal discount offer, etc. ## Send out Web Checkout links. Next, simply send out the [web checkout](/docs/web-checkout/web-checkout-creating-campaigns-to-show-paywalls) links to your users. You can create a link for each referral code, or you can use the same link for all of them.> **Tip:** Remember that with Superwall's web checkout feature, each placement you add becomes its own web checkout link. ## User converts. When the user clicks the link, they are taken to a web checkout page that has the discounted product you created in Stripe. They can enter their payment information and complete the purchase.And that's it! It's a matter of creating discounted products in Stripe, using them in a campaign, and then sending out the web checkout links to your users. You'll see all of the details in your campaign that you built for referrals, just like you would any other campaign, so you can track conversions, trial starts, and more.