# 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

# Payment Failure Reasons

Learn why a web payment failed (card declined, insufficient funds, expired card) and react with purchase callbacks that work on every platform.

When a Stripe purchase fails, `purchase()` tells you why in Superwall's own words: `card_declined`, `insufficient_funds`, `expired_card` and so on. The same reasons come back whichever payment method took the payment, so a paywall can branch on them without knowing Stripe's error codes. Use them to show the right message, offer another way to pay, or send the shopper back to your app from a [teleport](/docs/framework/teleport#return-to-the-app-after-a-failed-payment) page.

```tsx
import { usePurchase } from "superwall/hooks";

const { purchase } = usePurchase();

const result = await purchase("annual");
const failure = "failure" in result ? result.failure : undefined;
if (failure?.reason === "insufficient_funds") {
  setMessage("Your card was short on funds. Try another card or Apple Pay.");
}
```

## Requirements

* A Stripe product bought through [web checkout](/docs/framework/web-checkout): the embedded sheet, Apple Pay, the hosted checkout or a teleport.
* The exact reason comes from the payment itself. Where that payment ran out of reach of the page, the reason arrives once Superwall's backend reports it, see [What each purchase path reports](#what-each-purchase-path-reports).
* App Store, Play Store and custom store purchases report no reason, see the same table.

## The reasons

`failure.reason` is a `CheckoutFailureReason`, one of:

| Reason                   | Meaning                                                                  |
| ------------------------ | ------------------------------------------------------------------------ |
| `card_declined`          | The issuer declined and gave no more specific reason.                    |
| `insufficient_funds`     | Not enough money or credit on the card.                                  |
| `expired_card`           | The card has expired.                                                    |
| `incorrect_card_details` | A wrong number, CVC, expiry, postal code or PIN.                         |
| `authentication_failed`  | 3D Secure or another check by the bank failed or was cancelled.          |
| `card_not_supported`     | The card cannot pay for this kind of purchase or in this currency.       |
| `limit_exceeded`         | The card hit a spending, frequency or PIN-attempt limit.                 |
| `fraud_suspected`        | The issuer or Stripe flagged the payment, or the card is lost or stolen. |
| `processing_error`       | The issuer or the network failed; trying again may work.                 |
| `unknown`                | Nobody reported why, or the store gave a reason Superwall does not know. |

`unknown` is never a guess. A reason nobody reported stays `unknown`, so treat it as "something went wrong", not as any one of the others.

## What a failure holds

A failed web purchase carries a `CheckoutFailure`:

| Field         | Type                    | Meaning                                                                                            |
| ------------- | ----------------------- | -------------------------------------------------------------------------------------------------- |
| `reason`      | `CheckoutFailureReason` | Why it failed, from the table above.                                                               |
| `store`       | `"stripe"`              | The store that refused the payment.                                                                |
| `code`        | `string`, optional      | The store's own error code, such as Stripe's `card_declined`. Absent when the store sent none.     |
| `declineCode` | `string`, optional      | The issuer's decline code, such as Stripe's `insufficient_funds`. Absent when the store sent none. |
| `message`     | `string`, optional      | The store's message for the customer. Absent when the store sent none.                             |

Branch on `reason`. `code`, `declineCode` and `message` are Stripe's raw values, there for logging and for the rare case you need a code Superwall folds into a broader reason.

It reaches you in three places:

* `purchase()` resolves `{ status: "failed", product, failure }`.
* `usePurchase().failure` holds the last purchase that failed, with `status: "failed"` and the `product`, and clears when the next purchase starts.
* `onFailure` receives it, see [Callbacks](#callbacks).

## What each purchase path reports

| Purchase                                                                                                   | `failure.reason`                                                                                                                                                                                                                  |
| ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Stripe product, Apple Pay on the web (hosted web paywall, Web SDK, teleport page)                          | The exact reason, from Stripe as the wallet confirms the payment.                                                                                                                                                                 |
| Stripe product, embedded sheet (`checkout: "sheet"`)                                                       | The exact reason once Superwall's backend reports the checkout's last failed payment, `unknown` until then. A subscription checkout may still report `unknown`: Stripe may not expose the failed payment while the sheet is open. |
| Stripe product, hosted checkout (`external`, and every Stripe purchase inside an iOS app without teleport) | Not a supported path for reasons: the shopper pays on Superwall's page, and the framework only learns what the backend reports while it waits. Plan for `unknown`.                                                                |
| Stripe product, teleport, seen from the app                                                                | The page's own reason when the page [returns to the app](/docs/framework/teleport#return-to-the-app-after-a-failed-payment) after the failure; otherwise what the backend reports on the teleport, `unknown` until then.          |
| App Store product in the iOS SDK                                                                           | `unknown`: the SDK reports a failure with no detail. `superseded` when a newer purchase of the same product, or a reopened paywall, replaced it.                                                                                  |
| Play Store product in the Android SDK                                                                      | `superseded` as on iOS. Any other failure fires nothing: the Android SDK sends no failure message, see [Purchases](/docs/framework/purchases#the-three-outcomes).                                                                 |
| Custom store product                                                                                       | No reason and no callbacks.                                                                                                                                                                                                       |

A store failure is a `SuperwallPurchaseFailure` (exported from `superwall`) with `reason: "unknown" | "superseded"` and no `store` field; a web failure is a `WebCheckoutFailure`. Both are a `PurchaseFailure`, so check `"store" in failure` before reading `code` or `declineCode`.

## Callbacks

`usePurchase` takes five callbacks, each optional:

| Callback              | Fires when                                                                | Platforms                                           |
| --------------------- | ------------------------------------------------------------------------- | --------------------------------------------------- |
| `onStart(product)`    | The purchase started.                                                     | All                                                 |
| `onSubmit(product)`   | The shopper submitted payment in the sheet or authorized it in Apple Pay. | Web checkout only: the native SDKs do not report it |
| `onComplete(product)` | The purchase was paid.                                                    | All                                                 |
| `onAbandon(product)`  | The shopper left the checkout or the store's sheet without paying.        | All                                                 |
| `onFailure(failure)`  | A purchase failed, with why in `failure.reason`.                          | All                                                 |

They fire for App Store and Play Store products bought through the native SDK and for Stripe products bought on the web: the embedded sheet, Apple Pay, the hosted checkout and a teleport. Custom store products fire none of them.

Pass them in two places:

```tsx
// Every purchase on the paywall, whichever component started it.
const { purchase } = usePurchase({
  onFailure: (failure) => track("purchase_failed", { reason: failure.reason }),
});

// Only this one purchase, beside any passed to usePurchase.
await purchase("annual", {
  onSubmit: () => setStatus("Processing…"),
  onFailure: (failure) => setMessage(messageFor(failure.reason)),
});
```

* **`usePurchase(options)`** fires for every purchase on the paywall, from any component.
* **`purchase(product, options)`** fires only for that call's purchase, and only while it is in flight.

A few timings to know:

* **Embedded sheet.** A decline keeps the sheet open so the shopper can try another card. `onFailure` fires on each decline, in order; `purchase()` waits and resolves `completed` if a later card pays, or `failed` with the latest failure if the shopper closes the sheet.
* **Teleport, in the app.** `onFailure` fires as soon as the browser's payment fails, while the shopper can still try again there.
* **Teleport page.** Calling `useTeleport().returnToApp()` from `onFailure` returns to the app with `reason=failed`, see [Teleport](/docs/framework/teleport#return-to-the-app-after-a-failed-payment).

A callback that throws is logged and does not stop the others.

## Show a message per reason

```tsx
import type { CheckoutFailureReason } from "superwall/hooks";

const MESSAGES: Record<CheckoutFailureReason, string> = {
  card_declined: "Your card was declined. Try another card.",
  insufficient_funds: "Your card was short on funds. Try another card or Apple Pay.",
  expired_card: "That card has expired.",
  incorrect_card_details: "Check the card number, expiry and CVC.",
  authentication_failed: "Your bank couldn't confirm the payment. Try again.",
  card_not_supported: "That card can't pay for this. Try another one.",
  limit_exceeded: "Your card hit a limit. Try another card.",
  fraud_suspected: "Your bank blocked this payment. Try another card.",
  processing_error: "Something went wrong with the payment. Try again.",
  unknown: "The payment didn't go through. Try again.",
};

const { failure } = usePurchase();
const reason = failure && "store" in failure ? failure.reason : undefined;

{reason && <p role="alert">{MESSAGES[reason]}</p>}
```

Typing the map as `Record<CheckoutFailureReason, string>` makes TypeScript flag a reason you forgot.

## Types

All from `superwall/hooks`, except `SuperwallPurchaseFailure`, which comes from `superwall`:

| Type                       | What it is                                                                                                        |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `CheckoutFailureReason`    | The ten reasons above.                                                                                            |
| `CheckoutFailure`          | `reason`, `store`, `code`, `declineCode`, `message`.                                                              |
| `WebCheckoutFailure`       | A `CheckoutFailure` with `status: "failed"` and the `product`.                                                    |
| `PurchaseFailure`          | A `WebCheckoutFailure` or a store `SuperwallPurchaseFailure`; what `onFailure` and `usePurchase().failure` carry. |
| `SuperwallPurchaseFailure` | A store purchase that failed: `reason: "unknown" \| "superseded"`.                                                |
| `PurchaseCallbacks`        | The five callbacks.                                                                                               |
| `UsePurchaseOptions`       | What `usePurchase()` takes: the callbacks.                                                                        |
| `PurchaseOptions`          | What `purchase()` takes: `checkout`, `prepaidCards`, `postPurchase`, `stripeMetadata` and the callbacks.          |

## Related

* [Purchases](/docs/framework/purchases): the three outcomes and restoring.
* [Web Checkout](/docs/framework/web-checkout): modes, Apple Pay and the hosted checkout.
* [Teleport](/docs/framework/teleport): send the shopper back to the app after a failed payment.
* [Hooks reference](/docs/framework/hooks): `usePurchase` in full.