> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swiftaiboilerplate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# RevenueCat Setup

> Complete guide to configuring in-app subscriptions with RevenueCat

<Info>
  **Find complete step-by-step guide in your project:** [revenuecat.md](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/blob/main/docs/integrations/RevenueCat.md)
</Info>

## What You'll Set Up

<CardGroup cols={2}>
  <Card title="Subscriptions" icon="credit-card">
    Monthly and annual subscription plans
  </Card>

  <Card title="Paywall" icon="lock">
    Beautiful subscription UI (already built!)
  </Card>
</CardGroup>

## Prerequisites

* Apple Developer account (\$99/year)
* [RevenueCat account](https://revenuecat.com) (free tier available)
* Completed [Supabase Setup](/pages/guides/supabase-setup)

<Warning>
  Subscriptions are the trickiest integration to get right. Work through each step in order, and reach out if you get stuck.
</Warning>

## Part 1: App Store Connect Setup

<Steps>
  <Step title="Create Bundle Identifier">
    Go to **App Store Connect** → **Certificates, Identifiers & Profiles** → **Identifiers** (left menu) → **Add new identifier**.

    Create a new App ID with your bundle identifier (e.g., `com.yourcompany.yourapp`).
  </Step>

  <Step title="Enable Capabilities">
    Select your App ID and enable the required capabilities:

    * ✅ Push Notifications
    * ✅ In-App Purchase
    * ✅ Sign in with Apple
    * ✅ Associated Domains
    * ✅ Any other capabilities you need
  </Step>

  <Step title="Create New App">
    Go to **Apps** in App Store Connect and click **Create new app** (+ button).
  </Step>

  <Step title="Fill App Form">
    Fill the form with your bundle ID and create the app:

    * Platform: iOS
    * Name: Your App Name
    * Primary Language: English (or your language)
    * Bundle ID: Select the one you created
    * SKU: A unique identifier (e.g., `yourapp2024`)
  </Step>

  <Step title="Create Subscription Group">
    If you're adding subscriptions:

    1. Go to **Subscriptions** from the left menu
    2. Click **Create** to add a new subscription group
    3. Name it (e.g., "Premium Access")
  </Step>

  <Step title="Create Subscriptions">
    Create subscriptions under the subscription group:

    * Add **Monthly** subscription (e.g., `monthly_subscription`)
    * Add **Annual** subscription (e.g., `annual_subscription`)

    <Warning>
      Make sure to note down the **Product IDs** exactly as you create them. Arrange their order in **descending order** as described by Apple (longest duration first).
    </Warning>
  </Step>
</Steps>

## Part 2: RevenueCat Dashboard Setup

<Steps>
  <Step title="Create RevenueCat Project">
    Go to [RevenueCat](https://app.revenuecat.com) and create a new project:

    1. Click **Create New Project**
    2. Name your project
    3. Select **iOS** as platform
  </Step>

  <Step title="Create Offerings">
    Create a new offering in RevenueCat:

    1. Go to **Products** → **Entitlements**
    2. Create entitlement named `pro` (or your choice)
    3. Go to **Offerings** and create a new offering
    4. Add your subscription products to the offering

    <Warning>
      Make **100% sure** the entitlement name matches what you use in your app code and note it down.
    </Warning>
  </Step>

  <Step title="SDK Already Installed">
    The RevenueCat SDK is already installed in the boilerplate!

    Just make sure:

    * Package dependencies are resolved in Xcode
    * You have your **test API key** ready

    <Note>
      The remaining steps RevenueCat suggests (SDK initialization, configuration, entitlement checks) are already wired up in the `Payments` package, so you only need the API key and entitlement ID.
    </Note>
  </Step>

  <Step title="Update Config with API Key">
    Add your test API key to `Config/Secrets.xcconfig`:

    ```text theme={null}
    REVENUECAT_API_KEY = appl_YOUR_TEST_API_KEY
    RC_ENTITLEMENT_ID = pro
    ```

    Then run the update config script again:

    ```bash theme={null}
    bash scripts/update-config.sh
    ```

    This regenerates `SwiftAIBoilerplatePro/Generated/Configuration.swift` with your values.
  </Step>
</Steps>

## Part 3: Testing Configuration

<Steps>
  <Step title="Disable Auth Bypass">
    In Xcode, configure the scheme for testing:

    1. Select your target from top menu
    2. **Edit Scheme** → **Arguments** tab
    3. Under **Environment Variables**, set `AUTH_BYPASS` to `0` (or remove it)
  </Step>

  <Step title="StoreKit Configuration">
    For **simulator testing**:

    1. Select your target → **Edit Scheme**
    2. Go to **Options** tab
    3. **StoreKit Configuration** → select the bundled `StoreKitConfiguration.storekit` (in `SwiftAIBoilerplatePro/Resources/`)

    <Note>
      For **real device testing**, leave StoreKit Configuration set to **None**.
    </Note>
  </Step>

  <Step title="Verify Subscription Status">
    Make sure the statuses of your subscriptions are **Ready to Submit** in App Store Connect.

    Check each subscription product and ensure all required fields are filled.
  </Step>

  <Step title="App Store Connect API Key">
    Configure your App Store Connect API Key in RevenueCat:

    <Card title="RevenueCat Official Guide" icon="link" href="https://www.revenuecat.com/docs/service-credentials/itunesconnect-app-specific-shared-secret/app-store-connect-api-key-configuration">
      Follow RevenueCat's official documentation for App Store Connect API key setup
    </Card>

    <Note>
      We're not documenting this step in detail because when Apple changes it, RevenueCat updates their docs immediately.
    </Note>
  </Step>

  <Step title="Map Product IDs Correctly">
    In your RevenueCat offering, make sure to map the correct test product with your real App Store product.

    <Warning>
      Product IDs must match **exactly**. For example, if your 12-month subscription is mapped to a 1-month test product, it won't work. They must be mapped correctly.
    </Warning>
  </Step>

  <Step title="Verify Offerings Load">
    Run your app and navigate to the paywall. You should see your subscription offerings loading correctly.

    <Note>
      Detailed live RevenueCat logs are added to the project. If you have problems fetching products, analyze the console logs.
    </Note>
  </Step>
</Steps>

## Part 4: Sandbox Testing

<Steps>
  <Step title="Create Sandbox Account">
    Create a sandbox test account:

    1. Go to **App Store Connect**
    2. **Users and Access** → **Sandbox**
    3. Create a new sandbox tester account
  </Step>

  <Step title="Sign In on Device">
    On your simulator or device:

    1. Go to **Settings** → **Developer**
    2. Sign in with your **Sandbox Account**
    3. Try purchasing from your app
  </Step>

  <Step title="Common Issue: Bundle Mismatch">
    Be aware of this common issue: **Bundle ID mismatch** between App Store Connect and RevenueCat.

    <Warning>
      Make sure to upload a build to App Store Connect first. This registers your bundle ID properly and resolves many "products not found" issues.
    </Warning>
  </Step>

  <Step title="Verify on Dashboard">
    Check the RevenueCat customers dashboard after making a test purchase.

    <Note>
      It may take some time (up to an hour) for transactions to appear in the dashboard.
    </Note>
  </Step>
</Steps>

## What You Get

After setup:

* ✅ Working subscription purchases
* ✅ Beautiful paywall UI
* ✅ Subscription status tracking
* ✅ Restore purchases functionality
* ✅ Simulator testing with StoreKit Configuration
* ✅ Detailed logging for debugging

## Product Setup Example

**Monthly Subscription:**

* Product ID: `monthly_subscription`
* Type: Auto-Renewable Subscription
* Price: \$9.99/month

**Annual Subscription:**

* Product ID: `annual_subscription`
* Type: Auto-Renewable Subscription
* Price: \$79.99/year

## Troubleshooting

<AccordionGroup>
  <Accordion title="Products not loading">
    * Verify Product IDs match exactly in App Store Connect, RevenueCat, and StoreKit config
    * Upload a build to App Store Connect first
    * Check RevenueCat logs in console
    * Ensure subscription status is "Ready to Submit"
  </Accordion>

  <Accordion title="Purchase fails in sandbox">
    * Sign out of real App Store account
    * Sign in with sandbox account in Settings → Developer
    * Restart the app
    * Try again
  </Accordion>

  <Accordion title="Entitlement not granted">
    * Verify entitlement name matches in code and RevenueCat dashboard
    * Check that products are correctly mapped to entitlement
    * Wait a few minutes and check RevenueCat dashboard
  </Accordion>

  <Accordion title="Bundle ID mismatch error">
    * Ensure bundle ID in Xcode matches App Store Connect
    * Upload a test build to App Store Connect
    * Re-sync products in RevenueCat
  </Accordion>
</AccordionGroup>

## Related Guides

<CardGroup cols={2}>
  <Card title="Payments Module" icon="dollar" href="/pages/modules/payments">
    Technical documentation
  </Card>

  <Card title="Feature Settings" icon="gear" href="/pages/modules/feature-settings">
    Paywall UI details
  </Card>

  <Card title="Building Your App" icon="hammer" href="/pages/guides/building-your-app">
    Customize subscriptions
  </Card>

  <Card title="Supabase Setup" icon="server" href="/pages/guides/supabase-setup">
    Configure backend first
  </Card>
</CardGroup>

## Need Help?

* 📖 Check the troubleshooting section above
* 💬 [Create an issue](https://github.com/SwiftAIBoilerplatePro/SwiftAIBoilerplatePro-Distribution/issues)
* 🔍 Search [RevenueCat docs](https://docs.revenuecat.com)