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

# Payment Setup

> Set up subscription plans and monetize your a0 app

# Setting Up Payments

Add subscription-based monetization to your a0 app with our integrated payment system.

<Info>
  a0 payments currently support:

  * **Web**: Stripe (test and production)
  * **iOS**: Apple App Store (TestFlight / App Store)
  * **Android**: not supported yet
</Info>

<Warning>
  Apple payments do <strong>not</strong> work in the a0 app or Expo Go. To test iOS purchases, you must use
  TestFlight or a native iOS build.
</Warning>

<Info>
  You can manage plans in two ways:

  * Use the dashboard UI, or
  * Edit the canonical config file: `.a0/monetization.yaml` (this is what the Monetization tab edits).

  <br />

  If you're using the a0 coding agent, it **can** edit `.a0/monetization.yaml` and trigger provider sync. It should not ask you to do the setup manually.
</Info>

## Overview

The payment system consists of three main components:

1. **Features** - Entitlements users get (e.g., PRO, AD\_FREE, UNLIMITED\_STORAGE)
2. **Subscription Plans** - Pricing tiers that include one or more features
3. **Offerings** - Bundles of plans presented to users (REQUIRED for paywalls)

## Step-by-Step Setup

### 1. Navigate to Payments

<Steps>
  <Step title="Open Project Settings">
    In your a0 dashboard, go to your project and click on your **App Name** to access the settings.
  </Step>

  <Step title="Access Payments Tab">
    Click on the **Payments** tab to access the payment configuration.
  </Step>
</Steps>

### 2. Create Features

Features represent the entitlements or capabilities users get when they subscribe.

<Steps>
  <Step title="Add Your First Feature">
    Click **Add Feature** and create features like:

    * `PRO` - Access to premium content
    * `AD_FREE` - Remove all advertisements
    * `UNLIMITED_STORAGE` - No storage limits
    * `PRIORITY_SUPPORT` - 24/7 support access
  </Step>

  <Step title="Name Features Clearly">
    Use descriptive names that make it easy to understand what each feature provides.

    <Tip>
      Features can be reused across multiple subscription plans, so think of them as building blocks.
    </Tip>
  </Step>
</Steps>

### 3. Create Subscription Plans

<Steps>
  <Step title="Add New Plan">
    Click **Create Plan** to set up your first subscription tier.
  </Step>

  <Step title="Configure Plan Details">
    Each plan requires:

    * **Plan Name**: e.g., "Pro Plan", "Premium Subscription"
    * **At least 1 Feature**: Select from your created features
    * **At least 1 Pricing Tier**: Choose from weekly, monthly, or annual

    <Frame />
  </Step>

  <Step title="Set Pricing">
    Enter prices for each tier you want to offer:

    * **Weekly**: Best for short-term trials
    * **Monthly**: Most popular option
    * **Annual**: Offer discounts for long-term commitment
  </Step>
</Steps>

### 4. Sync to Payment Providers

<Warning>
  **Critical**: Your payments will NOT work until you sync your plans to the appropriate payment provider. This is the most common setup mistake.
</Warning>

<Steps>
  <Step title="Click Sync Plan">
    Under your created plan, click the **Sync Plan** button.

    <Frame />
  </Step>

  <Step title="Choose Provider">
    Select your payment provider:

    * **Stripe**: For Web
    * **Apple App Store**: For iOS (IPA)
  </Step>

  <Step title="Configure Sync Settings">
    **For Stripe:**

    * Toggle "Use Stripe sandbox environment" for testing
    * Must link your Stripe account first
    * Sync to sandbox for testing, production for live apps (both are supported on web)

    **For Apple App Store:**

    * Ensure your app is linked with valid Team ID
    * Sync creates products in App Store Connect (production). You test purchases via TestFlight using sandbox tester accounts.
    * Invalid Team ID will cause sync to fail
  </Step>

  <Step title="Start Sync">
    Click **Start Sync** to create the products in your payment provider.

    <Check>
      Once synced successfully, you'll see a confirmation and your products will be created in Stripe/App Store Connect.
    </Check>
  </Step>
</Steps>

### 5. Create Offerings

<Warning>
  **Important**: Offerings are REQUIRED for your paywall to display products. Without offerings, your paywall will be empty.
</Warning>

<Steps>
  <Step title="Create New Offering">
    Click **Create Offering** to bundle plans for your paywall.
  </Step>

  <Step title="Configure Offering">
    * **Name**: e.g., "Standard", "Launch Special", "Black Friday"
    * **Description**: Explain what's included
    * **Select Plans**: Choose which subscription plans to include
  </Step>

  <Step title="Set as Current">
    Mark which offering should be presented to users by default. This will be available as `offerings.current` in your code.
  </Step>
</Steps>

## Testing Your Setup

**Stripe Test Cards:**

* Success: `4242 4242 4242 4242`
* Decline: `4000 0000 0000 0002`

**Apple Sandbox:**

* Sync products to App Store Connect (production), then test purchases via TestFlight using sandbox tester accounts
* Subscriptions auto-renew rapidly for testing
* Payments will not work in the a0 app or Expo Go (use TestFlight / native builds)

## Implementation

Ready to integrate payments into your app? See the [Payment Implementation](/development/monetization/payment-implementation) guide for code examples and best practices.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Paywall shows no products">
    **Most common issue**: No offerings created or no current offering set

    Solution:

    * Create at least one offering
    * Include your subscription plans in the offering
    * Set one offering as "current"
    * Ensure plans are synced to payment providers
  </Accordion>

  <Accordion title="Payments not working in testing">
    **Most common issue**: Forgot to sync or synced to wrong environment

    Solution:

    * For Stripe testing: Ensure "Use Stripe sandbox environment" is checked
    * For iOS testing: Ensure you're testing via TestFlight or a native iOS build (not the a0 app / Expo Go)
    * Always sync after making changes to plans

    For IOS:

    * **Missing subscription metadata in App Store Connect**

    Note: Metadata is REQUIRED for App Store submission but may not always be required for TestFlight or native build testing
  </Accordion>

  <Accordion title="Stripe sync failing">
    Common causes:

    * Stripe is not connected to your a0 account
    * Using production keys in sandbox mode
    * Invalid API keys

    Fix: Connect Stripe in Settings → Integrations, then retry sync
  </Accordion>

  <Accordion title="Apple sync failing">
    Common causes:

    * Invalid Team ID in project settings
    * App not properly configured in App Store Connect
    * Missing agreements in App Store Connect

    Fix:

    * Verify Team ID and ensure app is set up in App Store Connect
    * Go to App Store Connect → Your App → Subscriptions
    * Fill out all required metadata fields (description, screenshots, etc.)
  </Accordion>

  <Accordion title="Plan changes not reflecting">
    Remember: You must sync every time you:

    * Change pricing
    * Add/remove features
    * Modify plan details

    Changes won't take effect until synced!
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Payment Implementation" icon="code" href="/development/monetization/payment-implementation">
    Learn how to implement payments in your app with code examples.
  </Card>

  <Card title="Test Payments" icon="flask-vial" href="/development/testing/native-build-testing">
    Build and test payment flows on real devices.
  </Card>
</CardGroup>