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

# How to Add In-App Purchases and Subscriptions to Your App (RevenueCat)

> Add subscriptions and in-app purchases to an iPhone app with RevenueCat: connect your account, have the AI create products and a paywall, sync them to App Store Connect, and test. Includes Apple's paywall rules, costs, and fixes for products that don't show up.

**To sell subscriptions or in-app purchases in an iPhone app, you use Apple's in-app purchase system (App Review Guideline 3.1.1 requires it for digital goods; US App Store apps may also link to a web checkout), create the products in App Store Connect, and show them on a paywall with clear prices and a Restore Purchases button.** Vibecode does most of this with [RevenueCat](https://www.revenuecat.com/), which handles purchases, receipts, and subscription status for you. In an **iOS app** (Swift) project, ask the agent for a subscription: it connects RevenueCat, creates the products in App Store Connect, builds the paywall, and tests a purchase in the cloud simulator. In a **Mobile app** (React Native) project, connect RevenueCat in the **Payment** tab, then ask the agent to create your products and paywall. RevenueCat is free up to \$2,500 in monthly tracked revenue, then 1% of tracked revenue.

> [!NOTE]
>
> **iOS app** (Swift) projects: ask the agent in chat, as described in [iOS App Projects](#ios-app-swift-projects). **Mobile app** (React Native) projects: follow the [Payment tab steps](#mobile-app-react-native-projects). Charging on the web? Use [Stripe](https://www.vibecodeapp.com/docs/monetization/stripe-setup.md) instead.

## In-App Purchases at a Glance

| | What it is | Where |
| - | - | - |
| **Apple Developer Program** | Required to sell anything on the App Store | \$99/year ([enroll](https://www.vibecodeapp.com/docs/guides/apple-developer-account.md)) |
| **Paid Apps Agreement, tax, and banking** | Must be active before purchases work on a phone, in TestFlight, or on the App Store | App Store Connect → **Business** |
| **RevenueCat account** | Handles purchases, receipts, and subscriber status | Free up to \$2,500 monthly tracked revenue, then 1% ([pricing](https://www.revenuecat.com/pricing/)) |
| **Products** | Your subscriptions and one-time purchases | Created by the agent in RevenueCat and App Store Connect |
| **Paywall** | The screen that shows your offers | Built by the agent in your app |
| **Apple's commission** | Apple's share of each sale | 15% in the App Store Small Business Program (up to \$1 million a year in proceeds), the standard rate above that |

[YouTube video player](https://www.youtube.com/embed/WcpOuc9TMp8)

## iOS App (Swift) Projects

In a native **iOS app** project, the agent sets up subscriptions from one message. Say what you want to sell, for example:

```text Example prompt wrap theme={null}
Add a monthly and a yearly subscription with a 7-day free trial, and a paywall for the premium features.
```

You need a paid Vibecode plan, an [Apple Developer Program](https://www.vibecodeapp.com/docs/guides/apple-developer-account.md) membership, and a RevenueCat account, which you can create in RevenueCat's own sign-in window. The agent then:

1. **Connects RevenueCat.** If your account isn't connected yet, it shows a link. Sign in or sign up in RevenueCat's window, and the agent carries on by itself. You never copy an API key.
2. **Picks the plans and prices** from your app and tells you what it chose and why, unless you asked to review them first. You can change prices, trials, and plans later.
3. **Creates the products in App Store Connect:** the subscription group, each subscription's price and trial (available worldwide unless you say otherwise), and the review screenshot of your paywall. If it needs your Apple account, it sends a secure Apple sign-in link once.
4. **Links RevenueCat to Apple** by creating Apple's In-App Purchase key and uploading it to RevenueCat. The key files never enter your project.
5. **Sets up RevenueCat:** the products, an entitlement (the access a purchase gives, such as `premium`), an offering with your plans, and the paywall.
6. **Adds it to your app:** the RevenueCat Swift packages, the paywall, premium features that switch on with the entitlement, **Restore Purchases**, and **Manage Subscription**.
7. **Tests a purchase in the cloud simulator**, with Apple's real purchase sheet in Apple's free test environment. It checks that buying turns on premium, that access survives a relaunch, and that restoring works.

> [!TIP]
>
> You can also start in the **Payment** tab: click **Connect RevenueCat**, and setup uses the bundle ID from your Xcode project.

### What's Left for You

* **Tax and banking.** Apple won't sell your subscriptions until the **Paid Apps Agreement**, tax forms, and bank account are done in App Store Connect under **Business**. If the agreement is waiting, the agent accepts it with your connected Apple account. Tax and banking are yours, and the agent walks you through each field.
* **Trying it on your iPhone (optional).** Ask the agent. It sets up an Apple sandbox test account for you, and you install the app with **Publish → Install**.
* **Publishing.** When you submit the app, the agent sends your subscriptions to App Review together with that version.

### Where Purchases Cost Money

| Where the app runs | What a purchase is |
| - | - |
| Cloud simulator | Apple's test environment, free |
| Your iPhone, installed with **Publish → Install** | Apple's sandbox, free, using the sandbox test account |
| [TestFlight](https://www.vibecodeapp.com/docs/guides/testflight.md) | Apple's sandbox, free, with the tester's own Apple ID |
| App Store | Real money |

## Mobile App (React Native) Projects

In a **Mobile app** project, you connect RevenueCat in the **Payment** tab and add Apple's keys in RevenueCat yourself.

### Before You Start

You'll need the following:

* A paid [**Vibecode plan**](https://www.vibecodeapp.com/docs/getting-started/plans-and-credits.md) (Plus or higher)
* [**RevenueCat Account**](https://www.revenuecat.com/) (sign up for free)
* [**Apple Developer Program Membership**](https://developer.apple.com/programs/) (\$99/year). See [How to Create an Apple Developer Account](https://www.vibecodeapp.com/docs/guides/apple-developer-account.md).
* A **Mobile app** (React Native) project

### Step 1: Connect Your RevenueCat Account

1. Open your project in Vibecode
2. Click the **Payment** tab

![Payment tab](https://mintcdn.com/vibecodeapp/JQrqIQnbuDoPhy-U/payments/payments-tab.png?fit=max\&auto=format\&n=JQrqIQnbuDoPhy-U\&q=85\&s=d52faee9cb592333c304f2a148d0579c)

3. Click **Connect RevenueCat**
4. Sign into your RevenueCat account in the popup
5. Authorize Vibecode to access your account
6. You'll be redirected back automatically

> [!TIP]
>
> If the popup is blocked, check your browser's popup settings and try again.

### Step 2: Configure Your App Identity

After connecting, you'll set up your app identity:

1. **Display Name** - Your app's name as it appears on the home screen
2. **Bundle Identifier** - A unique identifier for your app (Vibecode auto-generates one)

> [!WARNING]
>
> Your Bundle Identifier cannot be changed after your first build. Choose carefully!

Click **Continue** to complete the setup.

### Step 3: Configure RevenueCat Credentials

> [!NOTE]
>
> This step is critical! Without these credentials, your in-app purchases will not work.

For RevenueCat to communicate with App Store Connect, you need to set up two API keys in your RevenueCat dashboard:

#### App Store Connect API Key

1. Go to [App Store Connect](https://appstoreconnect.apple.com/) → **Users and Access** → **Integrations** → **App Store Connect API**
2. Click **Generate API Key** with "App Manager" access level
3. Download the `.p8` file (you can only download this once!)
4. Note your **Issuer ID** from this page
5. In RevenueCat, go to your app's settings and upload the `.p8` file
6. Enter your Issuer ID and Vendor number (found in App Store Connect under **Payments and Financial Reports**)

> [card] [App Store Connect API Key Configuration](https://www.revenuecat.com/docs/service-credentials/itunesconnect-app-specific-shared-secret/app-store-connect-api-key-configuration)
>
> Full Guide

#### In-App Purchase Key

1. Go to [App Store Connect](https://appstoreconnect.apple.com/) → **Users and Access** → **Integrations** → **In-App Purchase**
2. Click **Generate In-App Purchase Key**
3. Download the `.p8` file (you can only download this once!)
4. In RevenueCat, upload this key in the **In-app purchase key configuration** section
5. Add your Issuer ID and save

> [card] [In-App Purchase Key Configuration](https://www.revenuecat.com/docs/service-credentials/itunesconnect-app-specific-shared-secret/in-app-purchase-key-configuration)
>
> In-App Purchase Key Configuration

> [!WARNING]
>
> The In-App Purchase key is required. Without it, transactions will fail to be recorded when using StoreKit 2.

### Step 4: Create Your Product with AI

Ask the Vibecode AI to create your subscription or in-app purchase product:

**Example prompts:**

```text Monthly Subscription theme={null}
Create a monthly premium subscription for $4.99
```

```text Yearly with Trial theme={null}
Add a yearly subscription with a 7-day free trial
```

```text One-Time Purchase theme={null}
Create a one-time purchase to remove ads for $2.99
```

The AI will create the product in RevenueCat for you.

### Step 5: Create a Paywall

Ask the AI to create a paywall screen for your app:

**Example prompts:**

```text Basic Paywall theme={null}
Create a paywall screen showing my subscription options
```

```text Premium Upgrade theme={null}
Add a premium upgrade screen with monthly and yearly options
```

```text Feature Gate theme={null}
Show a paywall when users try to access pro features
```

![Paywall example](https://mintcdn.com/vibecodeapp/JQrqIQnbuDoPhy-U/payments/paywall-example.png?fit=max\&auto=format\&n=JQrqIQnbuDoPhy-U\&q=85\&s=3e24d1963a2c17dc5a223067ffad92a1)

### Step 6: Test in Vibecode

Before publishing, test your paywall inside Vibecode:

1. Preview your app
2. Navigate to where the paywall appears
3. Verify the products display correctly
4. Test the purchase flow

![Test store](https://mintcdn.com/vibecodeapp/JQrqIQnbuDoPhy-U/payments/test-store.png?fit=max\&auto=format\&n=JQrqIQnbuDoPhy-U\&q=85\&s=70f88970e9cffe7ae9dc5a9d79d6f8c3)

### Step 7: Sync Product with App Store Connect

> [!NOTE]
>
> This step creates your product in App Store Connect. You must complete this before your app can accept real payments.

Tell the AI to sync your product with App Store Connect:

**Example prompts:**

```text Sync Products theme={null}
Sync my RevenueCat products with App Store Connect
```

```text Publish Subscription theme={null}
Publish my subscription to App Store Connect
```

![Sync products prompt](https://mintcdn.com/vibecodeapp/JQrqIQnbuDoPhy-U/payments/prompt-to-sync-products.png?fit=max\&auto=format\&n=JQrqIQnbuDoPhy-U\&q=85\&s=cffa282142e048b33cc8d9ddea689567)

This creates the corresponding product in your App Store Connect account.

### Step 8: Complete Product Setup in App Store Connect

Your product was created but needs additional metadata before it can go live:

1. Go to [App Store Connect](https://appstoreconnect.apple.com/)
2. Click on your app in the bottom left
3. Navigate to **Monetization** → **Subscriptions** (or **In-App Purchases**)
4. Click on the subscription group that was created
5. Select your product

![App Store Connect subscriptions page](https://mintcdn.com/vibecodeapp/JQrqIQnbuDoPhy-U/payments/app-store-connect-subscriptions-page.png?fit=max\&auto=format\&n=JQrqIQnbuDoPhy-U\&q=85\&s=12fb9532b7ad4a7c69d82305fd7de5dd)

#### Add Required Metadata

For each product, you need to add:

* **Display Name** - What users see during purchase
* **Description** - Explain what the subscription includes
* **Screenshot** - A screenshot showing your subscription in action

![App Store Connect missing metadata](https://mintcdn.com/vibecodeapp/JQrqIQnbuDoPhy-U/payments/asc-missing-metadata.png?fit=max\&auto=format\&n=JQrqIQnbuDoPhy-U\&q=85\&s=5c85bf2e13b9772e9b4dc3b9ac3de946)

![App Store Connect paywall screenshot](https://mintcdn.com/vibecodeapp/JQrqIQnbuDoPhy-U/payments/asc-paywall-screenshot.png?fit=max\&auto=format\&n=JQrqIQnbuDoPhy-U\&q=85\&s=2ba91fb72924583c66b7c78df3406240)

> [!NOTE]
>
> Your product will show "Missing Metadata" status until you add all required information including the screenshot.

Once all metadata is complete, the status will change and your product is ready for submission.

## Apple's Rules for In-App Purchases and Paywalls

Apple checks these during App Review. Getting them wrong is a common reason for rejection under guideline 3.1:

* **Use Apple's in-app purchase for digital goods.** Subscriptions, premium features, in-game currency, and content used inside the app go through Apple (3.1.1). On the US App Store you may also link to your own web checkout; elsewhere that needs an Apple entitlement (3.1.1(a)). Physical goods and real-world services, such as deliveries or rides, use other payment methods.
* **Show clear prices and terms.** The paywall must say what the user gets, how much it costs, and how often they're billed.
* **Include Restore Purchases.** Users who reinstall or switch devices must be able to get back what they paid for.
* **Subscriptions must last at least 7 days** and provide ongoing value (3.1.2(a)).
* **Link your terms of use and privacy policy** on the paywall and in your App Store listing.
* **Submit your products with the app.** New in-app purchases must have complete metadata in App Store Connect and be submitted for review together with an app version.

In Mobile app projects, the App Store [Preflight](https://www.vibecodeapp.com/docs/getting-started/deploy-app-store.md#run-preflight-first) check reviews your paywall for Restore Purchases, clear pricing, and non-Apple payment code before you submit. In iOS app projects, the agent validates your subscriptions in App Store Connect and fixes what Apple reports before it submits them. More in the [App Store rejections checklist](https://www.vibecodeapp.com/docs/guides/app-store-review-guidelines.md).

## Troubleshooting

There are many common issues that can prevent your products from working correctly. Please go through all of them and make sure they do not impact you.

**Can't connect to RevenueCat?**

* Check that popups aren't blocked in your browser
* Try refreshing the page and connecting again
* Ensure you're signed into your RevenueCat account

**Products not showing up?**

* Click **Refresh** in the Payment Dashboard
* Verify products are created in both App Store Connect and RevenueCat
* Check that products are linked to the correct app in RevenueCat

**Product shows "Missing Metadata"?**

* Go to App Store Connect and add all required fields
* Make sure to upload a screenshot for the product
* Save your changes and the status will update

**Purchases failing in testing?**

* Ensure you're using a valid Sandbox Tester account
* Sign out of your regular Apple ID first
* Check that your app's bundle ID matches App Store Connect

**Products not appearing in TestFlight?**

When subscriptions or in-app purchase products don't appear in TestFlight, it's usually due to an incomplete setup in App Store Connect, such as missing legal entity information or unfinished agreements or tax information.

![App Store Connect Business Agreements](https://mintcdn.com/vibecodeapp/Nhtmc42THUQIP_4s/payments/asc-legal.png?fit=max\&auto=format\&n=Nhtmc42THUQIP_4s\&q=85\&s=bd08275ec50aafb766bf161c6101bf22)

To fix this:

* Go to [App Store Connect](https://appstoreconnect.apple.com/) → **Business** → **Agreements**
* Ensure your **Paid Apps Agreement** is active (not "New")
* Complete any pending legal entity information
* Fill out all required tax and banking information
* Make sure to also fill out all the metadata for your products in App Store Connect. You can do this by going to App -> Subscriptions -> Your Subscription -> Edit -> Metadata.

**Pending agreements blocking purchases?**

If you see a yellow warning banner in App Store Connect about updated agreements, you must clear all pending agreements before RevenueCat can process purchases.

![App Store Connect pending agreements warning](https://mintcdn.com/vibecodeapp/ZmiNAmHfQeMkut3S/payments/asc-agreements.png?fit=max\&auto=format\&n=ZmiNAmHfQeMkut3S\&q=85\&s=6b8781741f762eeb4c096e3eb080cb9c)

To fix this:

* The **Account Holder** (not just any team member) must sign in to App Store Connect
* Review and accept any updated license agreements shown in the yellow banner
* Check **Business** → **Agreements** for any other pending agreements
* Once all agreements are accepted, the yellow warning will disappear and purchases will work

## Frequently Asked Questions

> [accordion] Do I have to use Apple's in-app purchase?
>
> For digital content, features, and subscriptions used in your iPhone app, in-app purchase is required ([guideline 3.1.1](https://developer.apple.com/app-store/review/guidelines/)). On the US App Store you can also add a button or link to your own web checkout; outside the US that needs an Apple entitlement, which only some countries offer (3.1.1(a)). RevenueCat runs on top of Apple's in-app purchase system. Physical goods and services used outside the app can use other payment methods.

> [accordion] How much does RevenueCat cost?
>
> RevenueCat is free until your app makes \$2,500 in monthly tracked revenue. Above that it charges 1% of tracked revenue. Apple's commission is separate. Check [RevenueCat's pricing page](https://www.revenuecat.com/pricing/) for current terms.

> [accordion] How much does Apple take from in-app purchases?
>
> 15% if you're in the App Store Small Business Program (up to \$1 million in proceeds a year), and the standard commission above that. Apple's rates differ by country and program, so check App Store Connect for yours.

> [accordion] Can I test purchases without being charged?
>
> Yes. Purchases in TestFlight and development builds use Apple's sandbox, so nobody is charged. In iOS app projects, purchases in the cloud simulator are free too, and the agent can set up a sandbox test account for your iPhone. In Mobile app projects, create a sandbox tester in App Store Connect under **Users and Access → Sandbox** and sign in with it on your test device.

> [accordion] Why aren't my products showing up?
>
> Usually one of three things: the **Paid Apps Agreement** isn't active, the product is missing metadata (including its review screenshot) in App Store Connect, or the bundle ID doesn't match. See [Troubleshooting](#troubleshooting) above.

> [accordion] Can I add in-app purchases to a native Swift iOS app?
>
> Yes. In an **iOS app** (Swift) project, ask the agent to add a subscription. It connects RevenueCat, creates the products in App Store Connect, builds the paywall, and tests a purchase in the cloud simulator. See [iOS App Projects](#ios-app-swift-projects).

> [accordion] Can I use Stripe instead?
>
> For web apps, yes: see [Stripe Setup](https://www.vibecodeapp.com/docs/monetization/stripe-setup.md). Inside an iPhone app, digital goods use Apple's in-app purchase, and on the US App Store you can also link to a Stripe checkout on your website (3.1.1(a)).

## Next Steps

> [card] [Publish to the App Store](https://www.vibecodeapp.com/docs/getting-started/deploy-app-store.md)
>
> Submit your app and products for review

> [card] [Review Guidelines Checklist](https://www.vibecodeapp.com/docs/guides/app-store-review-guidelines.md)
>
> Avoid payment-related rejections

> [card] [TestFlight](https://www.vibecodeapp.com/docs/guides/testflight.md)
>
> Test purchases with beta testers

> [card] [Vibecode Pricing](https://www.vibecodeapp.com/pricing)
>
> Compare Vibecode plans


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.