Skip to main content
This guide walks you through setting up RevenueCat from scratch.
First run tip: If you haven’t configured products yet, disable the payments feature to avoid “offerings empty” errors: apps/mobile/features/feature-registry.tsx → featureFlags.payments = false. Re-enable after setup is complete.

​
Prerequisites

  • Apple Developer account ($99/year)
  • App created in App Store Connect
  • RevenueCat account (free tier available)

​
Step 1: App Store Connect

​
1.1 Create Subscription Products

  1. Go to App Store Connect
  2. Select your app → Monetization → Subscriptions
  3. Create a Subscription Group (e.g., “Premium”)
  4. Add your subscription products

​
1.2 Product Configuration

For each product, configure:
FieldExample
Product IDmobile_launch_monthly_sub
Reference Name”Monthly Subscription”
Duration1 Month
PriceSelect a price tier

​
1.3 Add Localization

Required! Each product needs at least one localization:
  1. Click on your product
  2. Go to Localizations → Add
  3. Add Display Name and Description
Products without localization won’t load in your app!

​
1.4 Accept Paid Apps Agreement

  1. Go to Agreements, Tax, and Banking
  2. Accept the Paid Apps Agreement
  3. Complete all required tax and banking information
Products won’t load until this agreement is active.

​
Step 2: RevenueCat Dashboard

​
2.1 Create Project

  1. Sign up at RevenueCat
  2. Create a new project
  3. Add your iOS app with the correct bundle ID

​
2.2 Connect App Store

  1. Go to Apps & providers → Your iOS app
  2. Add your App Store Connect Shared Secret:
    • In App Store Connect: Your App → General → App-Specific Shared Secret
    • Click “Generate” if you don’t have one
    • Copy and paste into RevenueCat

​
2.3 Import Products

  1. Go to Product Catalog → Products
  2. Click + New under your App Store app
  3. Enter the Product ID exactly as in App Store Connect
  4. Products should sync automatically

​
2.4 Create Entitlements

Entitlements define what features users get access to:
  1. Go to Product Catalog → Entitlements
  2. Click + New
  3. Create an entitlement (e.g., pro or premium)
  4. Attach your products to this entitlement

​
2.5 Create Offerings

Offerings group products for display in your paywall:
  1. Go to Product Catalog → Offerings
  2. Click + New
  3. Name it (e.g., default)
  4. Add packages:
    • $rc_monthly → your monthly product
    • $rc_annual → your yearly product
  5. Click Make Current to set as default

​
2.6 Get API Keys

  1. Go to API Keys in sidebar
  2. Copy your Public API Key
    • iOS: starts with appl_
    • Android: starts with goog_

​
Step 3: Configure Your App

​
3.1 Add API Keys

Update API keys in lib/payments/config.ts: 
export const REVENUECAT_CONFIG = {
  iosApiKey: "appl_your_api_key_here",
  androidApiKey: "goog_your_api_key_here",
};

​
3.2 Set Payment Provider

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

​
Step 4: Create a Paywall

RevenueCat lets you design paywalls without code:
  1. Go to Paywalls in RevenueCat dashboard
  2. Click + New Paywall
  3. Use the visual builder to design your paywall
  4. Add your products, benefits, and styling
  5. Assign the paywall to your offering
The <RevenueCatUI.Paywall /> component will automatically display this paywall.

​
Step 5: Testing

​
Create Sandbox Tester

  1. App Store Connect → Users and Access → Sandbox
  2. Click + to add a new tester
  3. Use a unique email (can be fake, e.g., [email protected])

​
Sign In on Device

  1. On your iPhone: Settings → App Store
  2. Scroll down to Sandbox Account
  3. Sign in with your sandbox tester credentials

​
Test a Purchase

  1. Build your app to your physical device
  2. Navigate to the paywall
  3. Complete a purchase using sandbox account
  4. Verify in RevenueCat dashboard → Customers
Sandbox purchases are free and can be repeated for testing.

​
Verification Checklist

Before testing, verify:
  • Paid Apps Agreement is Active (not pending)
  • Products have price set
  • Products have localization (name + description)
  • Products are attached to entitlements in RevenueCat
  • Offering is set as Current in RevenueCat
  • Sandbox account is signed in on device
  • Bundle ID matches between app and App Store Connect

​
Next Steps

Troubleshooting

Common errors and solutions

Paywall Best Practices

Design high-converting paywalls

​
Remove / Disable

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