Skip to main content
This guide walks through setting up Superwall from scratch.

​
Prerequisites

  • Apple Developer Account
  • App created in App Store Connect
  • Physical iOS device (simulator can’t test purchases)

​
1. Create Superwall Account

1

Sign Up

Go to superwall.com and create an account.
2

Create App

In the dashboard, create a new app for iOS.
3

Copy API Key

Go to Settings → API Keys and copy your iOS API Key (starts with pk_).

​
2. Configure API Keys

Update API keys in lib/payments/config.ts: 
export const SUPERWALL_CONFIG = {
  iosApiKey: "pk_your_ios_api_key",
  androidApiKey: "pk_your_android_api_key", // optional
};

​
2.1 Set Payment Provider

Update the feature registry: 
export const featureFlags = {
  payments: { enabled: true, provider: "superwall" },
  // ...
};

​
3. Create Products in App Store Connect

Superwall uses StoreKit to fetch product prices. You need products in App Store Connect.
1

Create Subscription Group

App Store Connect → Your App → Subscriptions → Create Group Example: “Premium Subscriptions”
2

Add Subscription Products

Add products to the group: - Product ID: your_app_monthly_sub - Price: Set your price - Duration: 1 Month Repeat for yearly, etc.
3

Add Localizations

Each product needs at least one localization: - Display Name: “Monthly Premium” - Description: “Access all features”
4

Check Status

Products should show “Ready to Submit” status.
Products won’t work until they’re at least “Ready to Submit”. New products can take 15-30 minutes to propagate.

​
4. Add Products to Superwall

1

Go to Products

Superwall Dashboard → Products → Add Products
2

Enter Product IDs

Add each product ID exactly as it appears in App Store Connect: - your_app_monthly_sub - your_app_yearly_sub

​
5. Create a Paywall

1

Go to Paywalls

Dashboard → Paywalls → Create Paywall
2

Choose Template

Pick a template or start from scratch.
3

Add Products

Drag your products onto the paywall. Configure: - Primary product (yearly recommended) - Secondary product (monthly)
4

Design

Customize the design, copy, and images.
5

Save

Save the paywall.

​
6. Create a Campaign

Campaigns link paywalls to placements.
1

Go to Campaigns

Dashboard → Campaigns → Create Campaign
2

Set Placement

Enter the placement name your app will call: - campaign_trigger (default in template) - Or create your own: upgrade_tapped, feature_locked, etc.
3

Assign Paywall

Select the paywall you created.
4

Activate

Set the campaign to Active (not Draft).
Campaigns in Draft status won’t show paywalls!

​
7. Test

1

Build on Device

Run the app on a physical device (not simulator).
2

Sign into Sandbox

On device: Settings → App Store → Sandbox Account → Sign in with test account.
3

Trigger Paywall

Go to Payments → Superwall in the app.
4

Verify

  • Paywall should appear with correct products - Prices should display (not NaN) - Purchase flow should work

​
Checklist

Before going live, verify:
  • API key configured in config.ts
  • Products created in App Store Connect
  • Products added to Superwall dashboard
  • Paywall designed with products
  • Campaign created and Active
  • Placement name matches code (campaign_trigger)
  • Tested on physical device with sandbox account

​
Next Steps

Overview

Learn about Superwall features

Troubleshooting

Common errors and solutions

​
Remove / Disable

To disable payments while you configure Superwall, set: apps/mobile/features/feature-registry.tsx → featureFlags.payments = false For production removal guidance, see Removing Features.