Complete Guide to Flutter In-App Purchases with RevenueCat

TL;DR

• Native in-app purchase implementation requires complex server-side receipt validation
• App Store Review tests with sandbox environment even on production builds
• RevenueCat handles all receipt validation, subscription management, and edge cases
• You keep your custom paywall UI - RevenueCat just handles the backend
• Free up to $2,500/month in revenue, then 1% fee
• This guide covers App Store Connect, Google Play Console, and RevenueCat setup end-to-end

If you've ever had an app rejected by Apple with the dreaded message about receipt validation and sandbox environments, you know the pain. After multiple rejections on my nutrition tracking app Nutrify, I decided to document the complete solution using RevenueCat.

Why RevenueCat Instead of Native Implementation?

Before diving into the implementation, let's understand why RevenueCat is often the better choice.

The Native Implementation Problem

When you use Flutter's in_app_purchase package, you need to:

1. Validate receipts server-side - Apple requires this for security
2. Handle sandbox vs production - App Store Review uses sandbox even on production builds
3. Implement webhook handlers - For subscription renewals, cancellations, refunds
4. Manage subscription state - Track expiration dates, grace periods, billing retries
5. Support both platforms - iOS and Android have completely different APIs

Here's what Apple's rejection message typically looks like:

"When validating receipts on your server, your server needs to be able to handle a production-signed app getting its receipts from Apple's test environment. The recommended approach is for your production server to always validate receipts against the production App Store first. If validation fails with the error code 'Sandbox receipt used in production,' you should validate against the test environment instead."

The RevenueCat Solution

RevenueCat abstracts all of this:

Your App → RevenueCat SDK → RevenueCat Servers → Apple/Google APIs
                                    ↓
                            Your app just asks:
                            "Is this user premium?"

You get:

• Automatic receipt validation (sandbox/production handled for you)
• Subscription state management
• Cross-platform unified API
• Dashboard for debugging issues
• Webhook support if you need server sync
• Free up to $2,500/month MTR

---

Part 1: App Store Connect Setup (iOS)

Before touching any code, you need to configure your products in App Store Connect.

Step 1.1: Verify Paid Apps Agreement

This is the most commonly missed step. Your in-app purchases won't work without it.

1. Go to App Store Connect
2. Click Business in the top navigation
3. Select the Agreements tab
4. Look for Paid Apps row
5. If status is not "Active", click View and Agree to Terms
6. Complete the banking and tax information if prompted

Important: Only the Account Holder can sign agreements. If you're not the Account Holder, contact them to complete this step.

Step 1.2: Create Your App (if not already created)

1. Go to Apps in App Store Connect
2. Click the + button → New App
3. Fill in:
   • Platform: iOS
   • Name: Your app name
   • Primary Language: Your language
   • Bundle ID: Select from dropdown (must match your Xcode project)
   • SKU: A unique identifier (e.g., com.yourcompany.yourapp)
4. Click Create

Step 1.3: Create In-App Purchase Products

Navigate to your app → Monetization → In-App Purchases (or Subscriptions for auto-renewable).

For Auto-Renewable Subscriptions:

1. Click Manage under Subscriptions
2. Click + to create a new Subscription Group
3. Name your group (e.g., "Premium Access")
4. Click Create

Now add products to the group:

1. Click + next to your subscription group

2. Fill in:

   • Reference Name: Internal name (e.g., "Monthly Premium")
   • Product ID: Unique identifier (e.g., yourapp_monthly)

   Important: Product IDs cannot be changed or reused after creation. Choose wisely.

3. Click Create

4. Configure the subscription:

   • Subscription Duration: 1 Month, 1 Year, etc.
   • Subscription Prices: Click + to add pricing
     • Select base country
     • Enter price
     • Optionally auto-generate prices for other countries
   • App Store Localization: Add display name and description for each language
   • Review Information: Add screenshot of subscription in use

5. Repeat for each subscription tier (Annual, Lifetime, etc.)

Example Product Configuration:

Step 1.4: Configure Free Trials (Optional)

For subscriptions with free trials:

1. Select your subscription product
2. Under Subscription Prices, click your price
3. Click Create Introductory Offer
4. Configure:
   • Type: Free Trial
   • Duration: 3 Days, 1 Week, etc.
   • Eligibility: All eligible customers

Step 1.5: Submit Products for Review

In-app purchases must be submitted with your app binary, but you can prepare them:

1. Ensure all products have status Ready to Submit
2. Each product needs:
   • Display name and description
   • At least one price point
   • Screenshot (for review)
3. Products will be reviewed when you submit your app

Step 1.6: Create Sandbox Test Account

For testing without real charges:

1. Go to Users and Access in App Store Connect
2. Click Sandbox in the left sidebar
3. Click + under Sandbox Testers
4. Fill in test account details:
   • First Name, Last Name
   • Email (must be unique, not a real Apple ID)
   • Password
   • Country/Region
5. Click Create

Tip: Use email aliases like yourname+sandbox1@gmail.com for easy management.

Step 1.7: Generate App Store Connect API Key (for RevenueCat)

RevenueCat needs API access to verify receipts:

1. Go to Users and Access → Integrations (or Keys)
2. Click + under "In-App Purchase"
3. Name it (e.g., "RevenueCat")
4. Click Generate
5. Download the .p8 file immediately - you can only download it once
6. Note down:
   • Issuer ID: Shown at the top
   • Key ID: Shown next to your key

---

Part 2: Google Play Console Setup (Android)

Step 2.1: Create Your App

1. Go to Google Play Console
2. Click Create app
3. Fill in app details and declarations
4. Click Create app

Step 2.2: Create In-App Products

Navigate to Monetize → Products → Subscriptions

1. Click Create subscription
2. Fill in:
   • Product ID: Must match iOS (e.g., nutrify_monthly)
   • Name: Display name
3. Click Create
4. Add a Base plan:
   • Base plan ID: (e.g., monthly-plan)
   • Auto-renewing: Yes
   • Billing period: Monthly
   • Price: Set pricing by region
5. Click Activate for the base plan

Repeat for each subscription tier.

Step 2.3: Create Service Account for RevenueCat

1. Go to Setup → API access
2. Click Link next to Google Cloud Project (or create one)
3. Under Service accounts, click Create new service account
4. Follow the link to Google Cloud Console
5. In Cloud Console:
   • Click Create Service Account
   • Name: "RevenueCat"
   • Click Create and Continue
   • Skip granting access, click Done
6. Click on the created service account
7. Go to Keys tab → Add Key → Create new key
8. Select JSON → Create
9. Download the JSON file
10. Back in Play Console, click Grant access for the service account
11. Set permissions:
    • Account permissions: None needed
    • App permissions: Select your app → Admin (all permissions)
12. Click Invite user → Send invitation

Note: It can take up to 24-48 hours for the service account permissions to propagate.

---

Part 3: RevenueCat Dashboard Setup

Step 3.1: Create RevenueCat Account

1. Go to RevenueCat
2. Click Get Started (free)
3. Create account with email or GitHub

Step 3.2: Create a Project

1. In the RevenueCat dashboard, click + New Project
2. Name your project (e.g., "Nutrify")
3. Click Create Project

Step 3.3: Configure iOS App

1. In your project, go to Apps in the left sidebar
2. Click + New App
3. Select App Store (iOS)
4. Fill in:
   • App Name: Your iOS app name
   • Bundle ID: Your app's bundle identifier (e.g., com.yourcompany.nutrify)
5. Click Save

Now connect to App Store Connect:

1. Click on your iOS app
2. Go to App Store Connect API section
3. Enter:
   • Issuer ID: From Step 1.7
   • Key ID: From Step 1.7
   • Private Key: Upload the .p8 file from Step 1.7
4. Click Save

Alternatively, use App-Specific Shared Secret:

1. In App Store Connect, go to your app → General → App Information
2. Under App-Specific Shared Secret, click Manage
3. Generate a secret and copy it
4. Paste in RevenueCat's App-Specific Shared Secret field

Step 3.4: Configure Android App

1. Click + New App again
2. Select Play Store (Android)
3. Fill in:
   • App Name: Your Android app name
   • Package Name: Your app's package (e.g., com.yourcompany.nutrify)
4. Click Save

Connect to Google Play:

1. Click on your Android app
2. Go to Service Account Credentials section
3. Upload the JSON key file from Step 2.3
4. Click Save

Step 3.5: Create Entitlements

Entitlements represent what features users unlock.

1. Go to Entitlements in the left sidebar
2. Click + New Entitlement
3. Configure:
   • Identifier: premium (you'll reference this in code)
   • Description: "Full access to all features"
4. Click Save

Step 3.6: Create Products

Products map to your App Store/Play Store products.

1. Go to Products in the left sidebar
2. Click + New Product
3. For each product:
   • Identifier: Match your store product ID (e.g., nutrify_monthly)
   • App: Select iOS or Android
   • Store Product ID: Same as identifier
4. Click Save
5. Click Attach to entitlement → Select premium

Create products for both iOS and Android, matching product IDs.

Step 3.7: Create Offerings

Offerings group products for display in your app.

1. Go to Offerings in the left sidebar
2. Click + New Offering
3. Configure:
   • Identifier: default
   • Description: "Default offering"
4. Click Save
5. Click + New Package
6. For each subscription tier:
   • Identifier: Use standard identifiers or custom
     • $rc_monthly - Monthly
     • $rc_annual - Annual
     • $rc_lifetime - Lifetime
   • Product: Select your product
7. Click Save

Step 3.8: Get API Keys

1. Go to API Keys in the left sidebar
2. Note down:
   • Public iOS API Key: appl_xxxxxxxx
   • Public Android API Key: goog_xxxxxxxx

Security Note: These are public keys - safe to include in your app. Never use your secret key in client code.

---

Part 4: Flutter Implementation

Now for the actual code. We'll integrate RevenueCat while keeping your existing paywall UI.

Step 4.1: Add Dependencies

Update your pubspec.yaml:

dependencies:
  purchases_flutter: ^8.1.0

Run:

flutter pub get

Step 4.2: iOS Configuration

Update ios/Podfile:

platform :ios, '13.0'  # RevenueCat requires iOS 13+

Add StoreKit capability in Xcode:

1. Open ios/Runner.xcworkspace in Xcode
2. Select your target → Signing & Capabilities
3. Click + Capability → Add In-App Purchase

Step 4.3: Android Configuration

Update android/app/build.gradle:

android {
    compileSdkVersion 34  // or higher

    defaultConfig {
        minSdkVersion 21  // RevenueCat minimum
    }
}

Add billing permission in android/app/src/main/AndroidManifest.xml:

<manifest>
    <uses-permission android:name="com.android.vending.BILLING" />
    <!-- ... -->
</manifest>

Step 4.4: Create RevenueCat Service

Create lib/core/services/revenuecat_service.dart:

import 'dart:io';
import 'package:flutter/foundation.dart';
import 'package:purchases_flutter/purchases_flutter.dart';

class RevenueCatService {
  // Replace with your actual API keys
  static const String _appleApiKey = 'appl_YOUR_IOS_KEY';
  static const String _googleApiKey = 'goog_YOUR_ANDROID_KEY';

  // Entitlement ID from RevenueCat dashboard
  static const String entitlementId = 'premium';

  static bool _isConfigured = false;

  /// Initialize RevenueCat - call this once at app startup
  static Future<void> initialize() async {
    if (_isConfigured) return;

    await Purchases.setLogLevel(LogLevel.debug); // Remove in production

    PurchasesConfiguration configuration;

    if (Platform.isIOS) {
      configuration = PurchasesConfiguration(_appleApiKey);
    } else if (Platform.isAndroid) {
      configuration = PurchasesConfiguration(_googleApiKey);
    } else {
      throw UnsupportedError('Platform not supported');
    }

    await Purchases.configure(configuration);
    _isConfigured = true;

    debugPrint('RevenueCat: Initialized successfully');
  }

  /// Login user - call after authentication
  static Future<void> login(String userId) async {
    try {
      await Purchases.logIn(userId);
      debugPrint('RevenueCat: Logged in user $userId');
    } catch (e) {
      debugPrint('RevenueCat: Login error - $e');
    }
  }

  /// Logout user - call on sign out
  static Future<void> logout() async {
    try {
      await Purchases.logOut();
      debugPrint('RevenueCat: Logged out');
    } catch (e) {
      debugPrint('RevenueCat: Logout error - $e');
    }
  }

  /// Check if user has active premium subscription
  static Future<bool> isPremium() async {
    try {
      final customerInfo = await Purchases.getCustomerInfo();
      final entitlement = customerInfo.entitlements.all[entitlementId];
      return entitlement?.isActive ?? false;
    } catch (e) {
      debugPrint('RevenueCat: Error checking premium status - $e');
      return false;
    }
  }

  /// Get current customer info
  static Future<CustomerInfo> getCustomerInfo() async {
    return await Purchases.getCustomerInfo();
  }

  /// Get available offerings (products to display)
  static Future<Offerings?> getOfferings() async {
    try {
      final offerings = await Purchases.getOfferings();
      return offerings;
    } catch (e) {
      debugPrint('RevenueCat: Error fetching offerings - $e');
      return null;
    }
  }

  /// Purchase a package
  static Future<PurchaseResult> purchasePackage(Package package) async {
    try {
      final customerInfo = await Purchases.purchasePackage(package);
      final isPremium =
          customerInfo.entitlements.all[entitlementId]?.isActive ?? false;

      return PurchaseResult(
        success: isPremium,
        customerInfo: customerInfo,
      );
    } on PurchasesErrorCode catch (e) {
      if (e == PurchasesErrorCode.purchaseCancelledError) {
        return PurchaseResult(
          success: false,
          userCancelled: true,
        );
      }
      return PurchaseResult(
        success: false,
        error: e.toString(),
      );
    } catch (e) {
      return PurchaseResult(
        success: false,
        error: e.toString(),
      );
    }
  }

  /// Restore previous purchases
  static Future<RestoreResult> restorePurchases() async {
    try {
      final customerInfo = await Purchases.restorePurchases();
      final isPremium =
          customerInfo.entitlements.all[entitlementId]?.isActive ?? false;

      return RestoreResult(
        success: isPremium,
        customerInfo: customerInfo,
      );
    } catch (e) {
      return RestoreResult(
        success: false,
        error: e.toString(),
      );
    }
  }

  /// Listen to customer info updates
  static void addCustomerInfoUpdateListener(
    void Function(CustomerInfo) listener,
  ) {
    Purchases.addCustomerInfoUpdateListener(listener);
  }
}

/// Result of a purchase attempt
class PurchaseResult {
  final bool success;
  final bool userCancelled;
  final String? error;
  final CustomerInfo? customerInfo;

  PurchaseResult({
    required this.success,
    this.userCancelled = false,
    this.error,
    this.customerInfo,
  });
}

/// Result of a restore attempt
class RestoreResult {
  final bool success;
  final String? error;
  final CustomerInfo? customerInfo;

  RestoreResult({
    required this.success,
    this.error,
    this.customerInfo,
  });
}

Step 4.5: Initialize at App Startup

In your main.dart or splash screen:

import 'package:your_app/core/services/revenuecat_service.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Initialize RevenueCat early
  await RevenueCatService.initialize();

  runApp(MyApp());
}

Step 4.6: Login User After Authentication

In your auth flow, after successful login:

// After user signs in
await RevenueCatService.login(user.uid);

And on logout:

// When user signs out
await RevenueCatService.logout();

Step 4.7: Create Subscription Provider

Create lib/ui/providers/subscription_provider.dart:

import 'package:flutter/foundation.dart';
import 'package:purchases_flutter/purchases_flutter.dart';
import 'package:your_app/core/services/revenuecat_service.dart';

class SubscriptionProvider extends ChangeNotifier {
  bool _isLoading = false;
  bool get isLoading => _isLoading;

  bool _isPremium = false;
  bool get isPremium => _isPremium;

  String? _errorMessage;
  String? get errorMessage => _errorMessage;

  Offerings? _offerings;
  Offerings? get offerings => _offerings;

  // Convenience getters for packages
  Package? get monthlyPackage =>
      _offerings?.current?.availablePackages
          .firstWhere(
            (p) => p.packageType == PackageType.monthly,
            orElse: () => _offerings!.current!.availablePackages.first,
          );

  Package? get annualPackage =>
      _offerings?.current?.availablePackages
          .where((p) => p.packageType == PackageType.annual)
          .firstOrNull;

  Package? get lifetimePackage =>
      _offerings?.current?.availablePackages
          .where((p) => p.packageType == PackageType.lifetime)
          .firstOrNull;

  SubscriptionProvider() {
    _init();
  }

  Future<void> _init() async {
    await Future.wait([
      checkPremiumStatus(),
      fetchOfferings(),
    ]);

    // Listen for subscription changes
    RevenueCatService.addCustomerInfoUpdateListener((customerInfo) {
      _isPremium = customerInfo.entitlements.all['premium']?.isActive ?? false;
      notifyListeners();
    });
  }

  Future<void> checkPremiumStatus() async {
    _isPremium = await RevenueCatService.isPremium();
    notifyListeners();
  }

  Future<void> fetchOfferings() async {
    _isLoading = true;
    _errorMessage = null;
    notifyListeners();

    _offerings = await RevenueCatService.getOfferings();

    if (_offerings?.current == null) {
      _errorMessage = 'No subscription plans available';
    }

    _isLoading = false;
    notifyListeners();
  }

  Future<bool> purchase(Package package) async {
    _isLoading = true;
    _errorMessage = null;
    notifyListeners();

    final result = await RevenueCatService.purchasePackage(package);

    _isLoading = false;

    if (result.success) {
      _isPremium = true;
      notifyListeners();
      return true;
    }

    if (!result.userCancelled) {
      _errorMessage = result.error ?? 'Purchase failed';
    }

    notifyListeners();
    return false;
  }

  Future<bool> restorePurchases() async {
    _isLoading = true;
    _errorMessage = null;
    notifyListeners();

    final result = await RevenueCatService.restorePurchases();

    _isLoading = false;

    if (result.success) {
      _isPremium = true;
      notifyListeners();
      return true;
    }

    _errorMessage = result.error ?? 'No purchases to restore';
    notifyListeners();
    return false;
  }
}

Step 4.8: Update Your Paywall UI

Here's how to use the provider in your existing paywall:

import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import 'package:your_app/ui/providers/subscription_provider.dart';

class PaywallScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Consumer<SubscriptionProvider>(
      builder: (context, provider, child) {
        if (provider.isLoading) {
          return Center(child: CircularProgressIndicator());
        }

        if (provider.errorMessage != null) {
          return Center(child: Text(provider.errorMessage!));
        }

        return Column(
          children: [
            // Your existing UI...

            // Monthly option
            if (provider.monthlyPackage != null)
              SubscriptionOption(
                title: 'Monthly',
                price: provider.monthlyPackage!.storeProduct.priceString,
                onTap: () => provider.purchase(provider.monthlyPackage!),
              ),

            // Annual option
            if (provider.annualPackage != null)
              SubscriptionOption(
                title: 'Annual',
                price: provider.annualPackage!.storeProduct.priceString,
                onTap: () => provider.purchase(provider.annualPackage!),
              ),

            // Lifetime option
            if (provider.lifetimePackage != null)
              SubscriptionOption(
                title: 'Lifetime',
                price: provider.lifetimePackage!.storeProduct.priceString,
                onTap: () => provider.purchase(provider.lifetimePackage!),
              ),

            // Restore button
            TextButton(
              onPressed: provider.restorePurchases,
              child: Text('Restore Purchases'),
            ),
          ],
        );
      },
    );
  }
}

Step 4.9: Check Premium Status Throughout App

Anywhere you need to check subscription status:

// Using provider
final isPremium = context.read<SubscriptionProvider>().isPremium;

// Or directly
final isPremium = await RevenueCatService.isPremium();

// Gate features
if (isPremium) {
  // Show premium feature
} else {
  // Show paywall or upgrade prompt
}

---

Part 5: Testing

Step 5.1: iOS Sandbox Testing

1. On your test device, go to Settings → App Store
2. Scroll down and tap Sandbox Account
3. Sign in with your sandbox tester credentials
4. Run your app and test purchases - you won't be charged

Tip: In sandbox, subscriptions renew rapidly:

• 1 week = 3 minutes
• 1 month = 5 minutes
• 1 year = 1 hour

Step 5.2: Android Testing

1. In Play Console, go to Setup → License testing
2. Add your test email addresses
3. Build and deploy to a test track (internal testing)
4. Test purchases - license testers won't be charged

Step 5.3: Verify in RevenueCat Dashboard

1. Go to Customers in RevenueCat dashboard
2. Search for your test user ID
3. You should see:
   • Transaction history
   • Active entitlements
   • Subscription status

Step 5.4: Test Edge Cases

Before submitting, test:

• New purchase flow
• Restore purchases (on fresh install)
• Cancel and resubscribe
• Upgrade from monthly to annual
• App behavior when subscription expires
• Offline behavior

---

Part 6: Webhook Integration (Optional)

If you need to sync subscription status to your backend (e.g., Firestore), set up webhooks.

Step 6.1: Create Webhook Endpoint

Example for Next.js/Vercel:

// app/api/revenuecat/webhook/route.ts
import { NextRequest, NextResponse } from 'next/server'

export async function POST(request: NextRequest) {
  // Verify authorization
  const authHeader = request.headers.get('authorization')
  if (authHeader !== `Bearer ${process.env.REVENUECAT_WEBHOOK_SECRET}`) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
  }

  const event = await request.json()

  console.log('RevenueCat webhook:', event.type)

  const userId = event.app_user_id
  const isActive = ['INITIAL_PURCHASE', 'RENEWAL', 'UNCANCELLATION'].includes(
    event.type
  )

  // Update your database
  await updateUserSubscription(userId, {
    active: isActive,
    productId: event.product_id,
    expiresAt: event.expiration_at_ms
      ? new Date(event.expiration_at_ms)
      : null,
    eventType: event.type,
  })

  return NextResponse.json({ received: true })
}

async function updateUserSubscription(userId: string, data: any) {
  // Your database update logic
  // e.g., Firestore, Supabase, etc.
}

Step 6.2: Configure in RevenueCat

1. Go to Integrations in RevenueCat dashboard
2. Click Webhooks
3. Enter your webhook URL
4. Add authorization header value
5. Select events to receive
6. Click Save

---

Troubleshooting Common Issues

"No products available"

1. Verify products are in Ready to Submit status in App Store Connect
2. Check product IDs match exactly (case-sensitive)
3. Ensure Paid Apps Agreement is signed
4. Wait 15-30 minutes after creating products

"Purchase not working in review"

1. App Store Review uses sandbox - ensure your app handles this
2. With RevenueCat, this is automatic
3. Check RevenueCat dashboard for any errors

"Restore not finding purchases"

1. User must be signed into same Apple/Google account
2. For testing, clear sandbox purchase history:
   • iOS: Settings → App Store → Sandbox → Manage → Clear Purchase History
3. Check RevenueCat dashboard for customer transaction history

Products showing wrong price

1. RevenueCat fetches prices from stores - verify in App Store Connect
2. Clear app cache and restart
3. Check you're using storeProduct.priceString not hardcoded prices

---

Checklist Before Submission

• Paid Apps Agreement signed in App Store Connect
• All products in "Ready to Submit" status
• Products configured in RevenueCat with correct IDs
• Entitlement created and products attached
• Offering created with packages
• API keys added to your app
• Tested new purchase in sandbox
• Tested restore purchases
• Tested subscription expiration behavior
• Removed debug logging in production

---

Conclusion

RevenueCat removes the complexity of in-app purchase implementation while letting you keep full control of your UI. The key benefits:

1. No server-side code needed for receipt validation
2. Automatic sandbox/production handling - App Store Review just works
3. Unified API for iOS and Android
4. Great debugging tools in the dashboard
5. Free up to $2,500/month in tracked revenue

The setup takes about 1-2 hours versus days for a custom implementation, and you get battle-tested code that's been through thousands of App Store reviews.

---

Resources

• RevenueCat Documentation
• Flutter SDK Reference
• App Store Connect Help
• Google Play Billing
• Sample Project

---

Have questions? Found this helpful? Let me know on Twitter.