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

# Adding Payments

> Monetize your app with subscriptions and purchases

# Adding Payments

This guide walks you through adding in-app purchases and subscriptions to your app using RevenueCat.

## Prerequisites

Before adding payments:

1. **Apple Developer Account** - Required for iOS purchases (\$99/year)
2. **Google Play Developer Account** - Required for Android (\$25 one-time)
3. **RevenueCat Account** - Free to start at [revenuecat.com](https://www.revenuecat.com)

<Card title="RevenueCat Integration" icon="credit-card" href="/integrations/revenuecat">
  Set up RevenueCat connection first
</Card>

## Step 1: Define Your Offering

Decide what you're selling:

<Tabs>
  <Tab title="Subscription">
    Recurring payments for ongoing access:

    * Monthly: \$9.99/month
    * Yearly: \$79.99/year (save 33%)
  </Tab>

  <Tab title="One-time Purchase">
    Single payment for permanent access:

    * Pro Upgrade: \$29.99 (remove ads forever)
  </Tab>

  <Tab title="Consumable">
    Single-use purchases:

    * 100 Credits: \$4.99
    * 500 Credits: \$19.99
  </Tab>
</Tabs>

## Step 2: Create Products in App Stores

<Steps>
  <Step title="App Store Connect (iOS)">
    1. Go to your app → Subscriptions
    2. Create a subscription group
    3. Add products with prices
    4. Submit for review
  </Step>

  <Step title="Google Play Console (Android)">
    1. Go to Monetization → Products → Subscriptions
    2. Create subscription products
    3. Set prices and billing periods
    4. Activate the products
  </Step>

  <Step title="RevenueCat Dashboard">
    1. Add your app to RevenueCat
    2. Configure store credentials
    3. Import products from stores
    4. Create entitlements (what users get access to)
  </Step>
</Steps>

## Step 3: Add Paywall to Your App

Ask the AI to create a paywall:

```
Create a premium subscription feature:

1. Create a paywall screen that shows:
   - App logo at the top
   - "Unlock Premium" heading
   - List of premium features with checkmarks
   - Monthly option: $9.99/month
   - Yearly option: $79.99/year (highlighted as "Best Value")
   - "Start Free Trial" button (7-day trial)
   - "Restore Purchases" link at bottom
   - Terms and Privacy links

2. When user taps a subscription option:
   - Show the system purchase dialog
   - Handle success: unlock premium, navigate to home
   - Handle failure: show error message

Use RevenueCat for payment processing.
```

## Step 4: Gate Premium Features

Lock features behind the subscription:

```
Make these features premium-only:
- AI chat (free users get 5 messages/day)
- Custom themes
- Cloud sync
- Remove ads

When a non-subscriber tries to access these features:
- Show a brief preview or explanation
- Display "Upgrade to Premium" button
- Tapping it navigates to the paywall screen
```

## Step 5: Check Subscription Status

The AI will generate code to check access:

```tsx theme={null}
// Example generated code
import Purchases from 'react-native-purchases';

const checkPremiumAccess = async () => {
  const customerInfo = await Purchases.getCustomerInfo();
  return customerInfo.entitlements.active['premium'] !== undefined;
};
```

### Show Status in UI

```
In the settings screen, show the user's subscription status:
- If subscribed: "Premium Member" with renewal date
- If not subscribed: "Free Plan" with upgrade button
```

## Step 6: Handle Restore Purchases

Important for returning users:

```
Add a "Restore Purchases" function:
1. Place it in Settings and on the paywall
2. When tapped, check for existing purchases
3. If found, restore access and show success message
4. If not found, show "No purchases to restore"
```

## Testing Purchases

<Warning>
  Never use real purchases during development. Always use sandbox/test accounts.
</Warning>

### iOS Sandbox Testing

1. Create Sandbox Apple ID in App Store Connect
2. Sign out of App Store on test device
3. Sign in with Sandbox account when making test purchase
4. Sandbox subscriptions renew quickly for testing

### Android Test Purchases

1. Add email as license tester in Play Console
2. Sign in with that account on test device
3. You'll see "(test)" badge on purchase dialogs
4. No real charges are made

## Subscription States

Handle different subscription states:

```
Handle these subscription scenarios:
- Active subscription: Show premium features
- Expired subscription: Show paywall with "Renew" messaging
- In free trial: Show "X days left in trial" banner
- Cancelled but still active: Show "Subscription ending on [date]"
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Clear Value First" icon="star">
    Show what premium offers before asking to pay
  </Card>

  <Card title="Offer Free Trial" icon="gift">
    Let users try before buying
  </Card>

  <Card title="Easy Restore" icon="rotate">
    Make restore purchases easily accessible
  </Card>

  <Card title="Transparent Pricing" icon="tag">
    Show prices clearly, no hidden fees
  </Card>
</CardGroup>

## App Store Requirements

Both stores have strict requirements:

### Apple App Store

* Digital goods MUST use Apple IAP
* Clearly state renewal terms
* Link to terms of service
* No external payment links

### Google Play Store

* Digital goods MUST use Google Play Billing
* Subscription terms visible before purchase
* Easy access to cancellation
* Clear pricing display

## Analytics and Revenue

Track your revenue in RevenueCat dashboard:

* Monthly Recurring Revenue (MRR)
* Active subscribers
* Trial conversions
* Churn rate
* Revenue by product

## Troubleshooting

<AccordionGroup>
  <Accordion title="Purchase not completing">
    * Verify products are approved in stores
    * Check RevenueCat configuration
    * Ensure correct product IDs
    * Test with sandbox account
  </Accordion>

  <Accordion title="Entitlement not granted">
    * Check RevenueCat dashboard for purchase
    * Verify entitlement linked to product
    * Check webhook configuration
  </Accordion>

  <Accordion title="Restore not finding purchases">
    * Same store account required
    * Check if subscription expired
    * Verify sandbox vs production
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Deploy Your App" icon="rocket" href="/features/deployment">
    Submit to app stores
  </Card>

  <Card title="RevenueCat Details" icon="credit-card" href="/integrations/revenuecat">
    Advanced RevenueCat features
  </Card>
</CardGroup>