# 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

# Debugging

Common issues and solutions when integrating the Superwall Expo SDK.

## Cannot find native module 'SuperwallExpo'

This error occurs when the native Superwall module isn't properly linked in your app. There are several common causes.

### Cause 1: Using Expo Go

**Expo Go does not support custom native modules.** Superwall requires native code that isn't included in Expo Go.

**Solution:** Use an [Expo Development Build](https://docs.expo.dev/develop/development-builds/introduction/) instead.

```bash
# For iOS
npx expo run:ios

# For Android
npx expo run:android
```

> **Note:** You can tell you're running Expo Go if the app icon is the Expo logo. Your development build will show your own app icon.

### Cause 2: Outdated Native Folders

If you added `expo-superwall` to an existing project, your `ios` and `android` folders may be outdated and missing the native module configuration.

**Solution:** Regenerate your native folders:

```bash
# Clean and regenerate native folders
npx expo prebuild --clean
```

This will delete your existing `ios` and `android` folders and regenerate them with the correct native module configuration.

> **Warning:** If you've made manual changes to your native folders, back them up first. The `--clean` flag will remove all custom native code.

### Cause 3: EAS Build Not Updated

If you're using EAS Build, you need to create a new development build after adding `expo-superwall`.

**Solution:** Build a new development client:

```bash
eas build --profile development --platform ios
# or
eas build --profile development --platform android
```

### Cause 4: Stale Caches

Cached build artifacts can cause issues after updating dependencies.

**Solution:** Clear all caches and rebuild:

```bash
# Clear watchman (if installed)
watchman watch-del-all

# Clear Expo cache
npx expo start --clear

# Remove and reinstall dependencies
rm -rf node_modules
npm install  # or yarn/pnpm/bun

# For iOS: reinstall pods
cd ios && pod install --repo-update && cd ..

# Rebuild
npx expo run:ios
```

### Cause 5: Version Incompatibility

Your Expo SDK version may not be compatible with `expo-superwall`.

**Solution:** Run the Expo doctor to check for issues:

```bash
npx expo-doctor
npx expo install --check
```

> **Warning:** Superwall requires **Expo SDK 53 or higher**. If you're on an older version, upgrade your Expo SDK first.

### Still Having Issues?

If none of the above solutions work:

1. **Completely clean rebuild:**
   ```bash
   rm -rf node_modules ios android .expo
   npm install
   npx expo prebuild --clean
   npx expo run:ios
   ```

2. **Verify the package is installed:**
   ```bash
   npm ls expo-superwall
   ```

3. **Check for conflicting packages** that might interfere with native module resolution