Revenuecat Testing Setup

revenuecat-testing-setup: set up a testing environment for RevenueCat purchases

Use this skill when the user wants to test purchases against RevenueCat without charging real money. Each store has its own testing channel, and each channel has different fidelity and iteration cost.

1. Detect the platform

Inspect the working directory and pick the first match, from top to bottom:

1. React Native: package.json has a react-native-purchases entry, or react-native as a dependency → read platforms/react-native.md. If expo is also a dependency, note it as an Expo project. 2. Flutter: pubspec.yaml exists at the project root → read platforms/flutter.md. 3. Kotlin Multiplatform: build.gradle.kts contains a kotlin { … } multiplatform source sets block, or depends on com.revenuecat.purchases:purchases-kmp* → read platforms/kmp.md. 4. Android (native): build.gradle(.kts) applies com.android.application (and is not KMP) → read platforms/android.md. 5. iOS (native): Package.swift, *.xcodeproj, *.xcworkspace, or Podfile at the project root → read platforms/ios.md.

If several match (e.g. an ios/ folder inside a Flutter project), pick the outermost project, the one that owns the build. If still ambiguous, ask the user which platform they want to configure.

2. Shared concepts (all platforms)

You cannot charge real money during development

Each store has a dedicated testing channel. Choosing the right channel depends on what you want to test.

Testing channels by fidelity vs iteration cost

Higher fidelity exercises more of the real purchase pipeline. Lower fidelity iterates faster.

• RevenueCat Test Store (lowest fidelity, fastest iteration, deterministic). A synthetic store hosted by RevenueCat. The SDK is configured with a test_… API key from the dashboard. Purchases open a Test Store dialog where you pick the outcome by hand: Successful Purchase, Failed Purchase, or Cancel. Purchases trigger entitlements, update CustomerInfo, and appear on the dashboard, but no Apple or Google call happens. Best for paywall iteration, integration tests, and CI smoke runs.
• iOS StoreKit Configuration File (low fidelity, Apple synthetic). Xcode stubs the store locally. Purchases succeed instantly with no App Store Connect round trip. Useful when you need StoreKit specific behavior. RevenueCat transactions in this mode may or may not appear on the dashboard depending on SDK version and intended routing, so it is not a faithful dashboard test.
• iOS Sandbox (real sandbox Apple ID) / Android Internal Testing (license tester). Real store backends, real RevenueCat dashboard ingestion, real receipts. Slower to iterate: build, install, wait for Play propagation or App Store Connect to register the product.
• TestFlight (iOS) / Closed or Open Testing (Android). Behaves very close to production. Receipts are production style. Transactions land in the production RevenueCat dashboard, not the Sandbox view.
• Production. Real money. Do not use for testing.

Start with the lowest fidelity that answers the question, then move up. UI and paywall iteration belongs in the fast channel. "Does my entitlement actually flip?" belongs in sandbox or internal testing.

Test Store: when to reach for it before sandbox

RevenueCat's Test Store is a synthetic store provider configured per project on the dashboard. It produces real RevenueCat backend records (CustomerInfo updates, entitlement transitions, dashboard transactions) without calling App Store or Google Play. The price of that speed is fidelity. Test Store does not simulate Ask to Buy approval flows, region specific pricing, server side receipt validation specifics, store level review or rejection paths, or full subscription renewal cadence (Test Store renews up to five times on a compressed clock).

Use Test Store when you want to iterate on UI quickly, write integration tests with deterministic outcomes, or run CI checks. Move up to App Store Sandbox or Google Play Internal Testing for anything that exercises store side behavior.

Setup. In the dashboard, go to Apps and providers → _Test configuration_ section → Test Store → Create / Enable. The Test Store API key appears under Project Settings → API keys with a test_ prefix. Configure the SDK with the test key in debug builds and the production key (appl_… / goog_…) in release builds. The platform files show the per platform key swap pattern.

Test Store keys must never ship to production. Gate the key behind your build configuration so release binaries cannot route through Test Store.

Sandbox transactions appear separately on the dashboard

The RevenueCat dashboard has a toggle between Sandbox and Production views. Sandbox purchases only appear under Sandbox. If a test transaction does not appear there, the SDK is not reporting it (check API key, configure call, and network), or the purchase was against a StoreKit config file that does not hit RevenueCat's backend.

Accelerated renewal in sandbox

Subscription renewals run on accelerated test clocks in sandbox. This lets you exercise renewal logic in minutes instead of weeks.

• iOS sandbox renewal cadence (per Apple's documentation): daily → every 3 minutes, weekly → every 3 minutes, monthly → every 5 minutes, 2 months → every 10 minutes, 3 months → every 15 minutes, 6 months → every 30 minutes, yearly → every hour. Subscriptions auto-renew a maximum of 6 times then expire.
• Android sandbox renewal cadence is documented in Google Play Console → Subscriptions testing. License tester subscriptions renew on the same accelerated clock.

Use a fresh test user for first purchase flows

Purchase history is attached to the test account (sandbox Apple ID or license tester Gmail) and persists. Testing "first purchase" logic, introductory offers, or free trials against an account that has already used them produces misleading results. Create a new sandbox tester for clean first purchase scenarios.

Confirm against the dashboard, not the device

A purchase succeeding on the device is not the same as RevenueCat recording it. Always confirm:

1. The transaction appears on the RevenueCat dashboard (Sandbox view). 2. The expected appUserID owns the transaction. 3. The expected entitlement is now active on that user.

If the device shows success but the dashboard shows nothing, something is wrong in the configuration path, not the store.

3. Implementation

Read the platform file that matches detection:

• platforms/ios.md
• platforms/android.md
• platforms/kmp.md
• platforms/flutter.md
• platforms/react-native.md

4. Verify

Your testing environment is set up once:

1. A test purchase succeeds end to end from a test user. 2. The transaction appears on the RevenueCat dashboard Sandbox view, attached to the appUserID you logged in with. 3. The expected entitlement is active on customerInfo after the purchase completes. 4. Restoring purchases on a fresh install of the app restores the entitlement to the same test user.

If any of those four steps fails, the environment is not ready. The revenuecat-troubleshoot skill covers the usual root causes.

revenuecat-testing-setup: Android (native Kotlin/Java)

Android stores have separate testing channels. RevenueCat Test Store works for any target store, since it does not call out to a real store, so use it for fast iteration regardless of where you ship. The real sandbox content further down covers Google Play (license testers on the Internal Testing track), which is the dominant target. Amazon Appstore and Samsung Galaxy Store have their own sandboxes; see the per store note before the sandbox section.

Test Store (RevenueCat synthetic store)

Best for: paywall UI iteration, deterministic purchase outcome scenarios, integration tests, CI smoke runs.

Not suitable for: Google Play specific behavior such as real receipt validation, Play Billing edge cases, or store level rejection flows. Use the sandbox flow further down for those.

The SDK calls are unchanged. The only difference is the API key passed to Purchases.configure(...). Use a test_… key in debug builds and your goog_… key in release builds, gated by build type so the test key cannot ship.

Step 1: enable in the dashboard

Dashboard → Apps and providers → _Test configuration_ → Test Store → Create / Enable. The Test Store API key appears under Project Settings → API keys with the test_ prefix.

Step 2: gate the key by build type

Use buildConfigField so the test key never compiles into a release binary.

app/build.gradle.kts:

android {
    buildFeatures { buildConfig = true }
    buildTypes {
        debug {
            buildConfigField("String", "REVENUECAT_API_KEY", "\"test_YOUR_TEST_STORE_KEY\"")
        }
        release {
            buildConfigField("String", "REVENUECAT_API_KEY", "\"goog_YOUR_PRODUCTION_KEY\"")
        }
    }
}

Configure the SDK from your Application class:

Purchases.configure(
    PurchasesConfiguration.Builder(this, BuildConfig.REVENUECAT_API_KEY).build()
)

Step 3: trigger a purchase

The first call to Purchases.sharedInstance.awaitPurchase(...) (or the callback variant) opens the Test Store dialog with three buttons: Successful Purchase, Failed Purchase, Cancel. Pick the outcome you want to test.

Verify

1. Logcat shows the SDK configured with a test_ key. 2. Successful Purchase routes through the success path; the entitlement on the returned CustomerInfo is active. 3. Failed Purchase and Cancel route through the same PurchasesException / userCancelled paths your app already handles for real Play purchases.

Per store: which sandbox applies

The sandbox flow below covers Google Play only. If you ship to Amazon Appstore (amzn_… API key) or Samsung Galaxy Store, the testing channel is different. Configure those through each store's developer console and follow its testing docs:

• Amazon Appstore (IAP Testing Overview): <https://developer.amazon.com/docs/in-app-purchasing/iap-testing-overview.html>
• Samsung IAP (Test Guide): <https://developer.samsung.com/iap/iap-test-guide.html>

Test Store described above works for any target store and stays as is.

Real sandbox: Google Play license tester on Internal Testing

Real sandbox testing on Google Play requires all three of: a license tester account, a signed build on the Internal Testing track, and live (not draft) products in Play Console.

Add license testers

1. Google Play Console → Setup → License testing. 2. Add the Gmail accounts that will be used for testing. 3. Set License response to RESPOND_NORMALLY. Other values simulate error conditions.

License testers pay a cartoon price instead of real money when they buy licensed products (usually labelled "test card, always approves") and can trigger renewal scenarios on Google's accelerated test clock.

Upload to the Internal Testing track

This is the step most often skipped. A sideloaded debug build with a debug signing key cannot purchase licensed products, even for license testers.

1. Build a signed AAB (release or a dedicated test variant). The signing key must match the upload key expected by Play Console, or be uploaded under Play App Signing. 2. Play Console → Release → Testing → Internal testing → create a release, upload the AAB. 3. Add your license tester Gmail accounts to the tester list for this track. 4. Publish the release to the track. 5. Share the opt-in link with testers. Each tester must click it, accept, and install the app from the Play Store link on their device.

Fresh uploads take roughly 15 minutes to propagate through Play. If a tester opens the opt-in link and the Play Store says "not available in your country" or similar, wait and retry.

Verify products are active in Play Console

Play Console → Monetize → In-app products (one-time) or Monetize → Subscriptions.

• One-time products must be Active.
• Subscriptions must have at least one Active base plan.
• Product IDs are case sensitive and cannot be reused after deletion.

A product that exists but is not Active, or a subscription without an active base plan, will not be returned by the Play Billing client. This shows up as an empty offerings list in RevenueCat.

applicationId must match

The signed AAB's applicationId must match:

• The app registered in Play Console (obvious).
• The Android app registered in the RevenueCat dashboard (often overlooked).

Flavor builds with suffixed application IDs (com.example.myapp.dev) need their own Play Console entry and their own RevenueCat app entry, or they will fail with no match.

Run and purchase

Install via the Play opt-in link (not Android Studio, not adb install). Sign into the device with a license tester account. Trigger the purchase. Play shows a "test card, always approves" dialog. On confirmation, the purchase flows through Play Billing into RevenueCat.

The transaction should appear on the RevenueCat dashboard Sandbox view within seconds.

Accelerated renewal

Google Play subscriptions bought by license testers renew on the accelerated clock documented in Play Console → Subscriptions testing. Use this to test renewal callbacks, grace period, and billing retry logic.

Clear purchase history for a fresh test

Play does not provide a one click clear for tester purchase history. Options:

• Use a different license tester Gmail for the next test run.
• Cancel the active subscription via Play Store → Subscriptions on the test device, wait for it to expire (fast on the test clock), then retry.

Subscription test clocks (optional)

Play Console offers subscription test accounts with configurable test clocks for more advanced renewal scenarios. These are separate from license testers and exercise different code paths. Documented under Play Console → Subscriptions testing.

Verify

1. Purchases.logLevel = LogLevel.DEBUG in the build. 2. App is installed from the Play Internal Testing opt-in link. 3. Device is signed in with a license tester Gmail. 4. A purchase succeeds, Play shows "test card, always approves". 5. Logcat shows the SDK posting the purchase. 6. The RevenueCat dashboard Sandbox view shows the transaction on the expected appUserID. 7. A fresh getCustomerInfo(...) call shows the expected entitlement active.

revenuecat-testing-setup: Flutter

purchases_flutter runs against the native iOS and Android SDKs. Testing a Flutter app is testing each platform against its native store's testing channel. Flutter itself does not add a testing mode.

Test Store (RevenueCat synthetic store)

Best for: paywall UI iteration, deterministic purchase outcome scenarios, integration tests, CI smoke runs.

Test Store works the same way on both Flutter targets. Pass a test_… API key in debug builds and your platform appl_… / goog_… keys in release builds. A single Test Store key from the dashboard covers both targets.

The cleanest pattern is --dart-define:

flutter run --dart-define=REVENUECAT_TEST_KEY=test_YOUR_TEST_STORE_KEY

In lib/main.dart:

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

const _testKey = String.fromEnvironment('REVENUECAT_TEST_KEY');
const _prodKeyIOS = 'appl_YOUR_IOS_PRODUCTION_KEY';
const _prodKeyAndroid = 'goog_YOUR_ANDROID_PRODUCTION_KEY';

String _apiKey() {
  if (kReleaseMode) {
    return Platform.isIOS ? _prodKeyIOS : _prodKeyAndroid;
  }
  return _testKey;
}

await Purchases.configure(PurchasesConfiguration(_apiKey()));

Or use Flutter flavors: each flavor compiles its own API key constant and maps to its own RevenueCat dashboard app entry.

Trigger a purchase. The Test Store dialog opens with Successful Purchase, Failed Purchase, Cancel. Pick an outcome and verify the resulting CustomerInfo and dashboard transaction.

The kReleaseMode branch above ensures the test key string is dead code in release builds and gets eliminated.

Set up each platform

Follow the platform files directly:

• iOS → revenuecat-testing-setup/platforms/ios.md. Prefer a real sandbox Apple ID for RevenueCat dashboard verification.
• Android → revenuecat-testing-setup/platforms/android.md. License tester on the Internal Testing track is required.

Build and install the right build

Flutter supports multiple ways to install a test build. Only the signed, correctly identified ones will work for real purchase testing.

iOS

• flutter run on a connected iOS device with a development provisioning profile works for sandbox testing with a sandbox Apple ID.
• flutter build ipa → distribute via TestFlight for TestFlight style testing. Note: TestFlight purchases land on the production dashboard view, not sandbox.

Android

• flutter build appbundle --release → signed AAB → upload to Play Internal Testing → install via the tester opt-in link. This is the only supported path for sandbox purchases.
• flutter run produces a debug build signed with the debug key. It will not be able to make sandbox purchases, because Play rejects the signature.

Multi flavor apps

Flutter apps frequently ship multiple flavors (dev, staging, prod) with different bundle identifiers / applicationIds. Each flavor needs:

• A matching App Store Connect or Play Console app entry, with its own products.
• A matching entry in the RevenueCat dashboard, with its own API key.

A common mistake: testing the dev flavor with the prod API key. Offerings come back empty because the dashboard has no app matching the dev bundle identifier.

Branch on the flavor (via --dart-define=FLAVOR=dev or equivalent) to pick the right API key at configure time.

Platform consoles for logs

When testing, watch the platform console, not just the Dart console:

• iOS → Xcode (attached to flutter run) shows the native SDK logs.
• Android → flutter logs or adb logcat -s Purchases shows the native SDK logs.

The Dart print output does not show native SDK logs.

Hot restart does not re-configure the SDK

Purchases.configure(...) runs once per native process launch. After changing the API key, observer mode setting, or any configuration value, kill the app fully and relaunch. Hot reload and hot restart keep the old SDK state.

Verify

1. await Purchases.setLogLevel(LogLevel.debug); before configure. 2. The right build (signed AAB from Play Internal Testing on Android; development build on a sandbox device on iOS) is installed. 3. A test purchase succeeds. Native console shows the SDK posting the transaction. 4. The RevenueCat dashboard Sandbox view shows the transaction on the expected appUserID. 5. await Purchases.getCustomerInfo() shows the expected entitlement active. 6. Drop log level back to LogLevel.info before shipping.

Run all of those steps on iOS and Android separately.

revenuecat-testing-setup: iOS (native)

iOS has four testing channels. Pick the lowest fidelity that answers your question, then move up.

Option A: Test Store (RevenueCat synthetic store)

Best for: paywall UI iteration, deterministic purchase outcome scenarios, integration tests, CI smoke runs.

Not suitable for: App Store specific behavior (Ask to Buy approval, region pricing, full subscription renewal fidelity beyond five compressed cycles, store level rejection flows). Move to Option C for those.

The SDK calls themselves are unchanged. The only difference is the API key you pass to Purchases.configure(withAPIKey:). Use the test_… key in debug builds and your production appl_… key in release builds, gated by build configuration so the test key cannot ship.

Step 1: enable in the dashboard

Dashboard → Apps and providers → _Test configuration_ → Test Store → Create / Enable. The Test Store API key appears under Project Settings → API keys with the test_ prefix.

Step 2: gate the key by build configuration

Use xcconfig files so the test key never compiles into a release binary.

Debug.xcconfig:

REVENUECAT_API_KEY = test_YOUR_TEST_STORE_KEY

Release.xcconfig:

REVENUECAT_API_KEY = appl_YOUR_PRODUCTION_KEY

Add an entry in Info.plist so the value is reachable at runtime:

<key>RevenueCatAPIKey</key>
<string>$(REVENUECAT_API_KEY)</string>

Configure the SDK from your app entry point:

let apiKey = Bundle.main.infoDictionary?["RevenueCatAPIKey"] as? String ?? ""
Purchases.configure(withAPIKey: apiKey)

If you prefer Swift over Info.plist plumbing, branch in code with #if DEBUG and hardcode the test key inside the debug branch only. The xcconfig path is more robust because it removes the test key from the compiled release binary entirely.

Step 3: trigger a purchase

The first call to Purchases.shared.purchase(package:) opens the Test Store dialog with three buttons: Successful Purchase, Failed Purchase, Cancel. Pick an outcome and verify the resulting CustomerInfo matches the path you expected.

Verify

1. Xcode console shows the SDK configured with a test_ key. 2. Picking Successful Purchase flips the entitlement on the returned CustomerInfo; the dashboard records the transaction. 3. Picking Failed Purchase or Cancel routes through the same error / userCancelled paths your app already handles for the real store.

Option B: StoreKit Configuration File (fastest, lowest fidelity)

Best for: paywall UI iteration, purchase sheet layout, offer display.

Not suitable for: "does the transaction hit the RevenueCat dashboard" verification. StoreKit config purchases run against Xcode's synthetic store and do not flow through Apple's sandbox servers.

Create the configuration file

1. In Xcode, File → New → File → StoreKit Configuration File. 2. Save it inside the project (e.g. Configuration.storekit). 3. Open the file. Click + at the bottom and add products (consumable, non-consumable, auto-renewing subscription, etc.). Match the product IDs to the IDs you have or will have in App Store Connect, so the same code works against both channels.

Wire the configuration to the scheme

Product → Scheme → Edit Scheme → Run → Options → StoreKit Configuration → pick the file.

Run

With the configuration wired and the scheme selected, running the app in the simulator or on a device uses the synthetic store. Purchases succeed immediately, no App Store login prompt, no network call.

To exit this mode, set the StoreKit Configuration on the scheme back to None.

Option C: Real sandbox (Apple ID sandbox tester)

Best for: end to end verification against the RevenueCat dashboard.

Create a sandbox tester

1. App Store Connect → Users and Access → Sandbox tab → Testers → +. 2. Enter an email that is not tied to a real Apple ID. A plus addressed alias on your own domain works (for example tester+rc@example.com). 3. Set a region that matches the storefront you want to test.

Add the sandbox account to the device

On iOS 14+:

1. Settings → App Store → scroll to Sandbox Account → Sign In. 2. Enter the tester credentials.

You do not need to sign out of your production Apple ID. The system routes purchases in development/TestFlight builds through the sandbox account.

Set products to "Ready to Submit" in App Store Connect

Sandbox will not return products in draft state. Each product must be Ready to Submit or further along in its lifecycle. Fresh products can take up to a few hours to become available in sandbox after creation.

Run and purchase

With a development build installed on the device, trigger a purchase. iOS prompts for the sandbox password on first use. The transaction should appear on the RevenueCat dashboard Sandbox view within a few seconds.

Accelerated renewal (per Apple's docs)

Monthly subscriptions renew every 5 minutes, yearly every hour, weekly every 3 minutes, and so on. A sandbox subscription auto-renews a maximum of 6 times, then expires. Use this to exercise renewal callbacks, grace periods, and billing retry logic.

Clear purchase history for a fresh test

Sandbox purchase history sticks to the tester account. To re-test a first purchase flow (including free trials and intro offers), create a new sandbox tester or use App Store Connect → Sandbox → Testers → select tester → clear purchase history.

Option D: TestFlight

Best for: pre-release smoke testing of the real production path.

TestFlight builds are receipt validated through production Apple servers. Transactions appear on the Production view of the RevenueCat dashboard, not Sandbox. TestFlight purchases are free but behave identically to production in the SDK's eyes.

Use TestFlight once you have already verified your integration in sandbox. It is not meant to replace sandbox testing.

Verify

1. Purchases.logLevel = .debug in the build. 2. A sandbox purchase completes on the device. 3. Xcode console shows the SDK logging the transaction (look for PostedTransaction or Purchase succeeded style log lines). 4. The RevenueCat dashboard Sandbox view shows the transaction with the expected appUserID. 5. Purchases.shared.customerInfo() after the purchase shows the expected entitlement active.

revenuecat-testing-setup: Kotlin Multiplatform

purchases-kmp delegates to the native iOS and Android SDKs. Testing a KMP app is testing each target against its native store's testing channel. There is no KMP specific sandbox.

Test Store (RevenueCat synthetic store)

Test Store works on either platform target. Because purchases-kmp delegates to the native SDKs, the mechanism is the native one: pass a test_… API key in debug builds and the production appl_… (iOS) or goog_… (Android) key in release builds, gated by the platform's build configuration.

• iOS target: see the Test Store section in revenuecat-testing-setup/platforms/ios.md for the xcconfig + Info.plist pattern.
• Android target: see the Test Store section in revenuecat-testing-setup/platforms/android.md for the buildConfigField per build type pattern.

A single Test Store key from the dashboard covers both targets. Read the resolved key from each platform's entry point and forward it into your shared init function rather than hardcoding it in commonMain. That keeps the test key out of the release binary on each target independently.

// commonMain
fun initRevenueCat(apiKey: String) {
    Purchases.configure(PurchasesConfiguration.Builder(apiKey = apiKey).build())
}

The Test Store dialog and outcome semantics are identical to the native SDKs: Successful Purchase, Failed Purchase, Cancel.

Set up each target

Follow the platform files directly:

• iOS target → revenuecat-testing-setup/platforms/ios.md. Prefer a real sandbox Apple ID when exercising RevenueCat dashboard ingestion. The StoreKit Configuration File is useful for pure UI iteration but does not hit the real sandbox pipeline.
• Android target → revenuecat-testing-setup/platforms/android.md. License tester on the Internal Testing track is required.

Match API keys

When testing each target, confirm the KMP app passes the right API key per platform:

• Android → goog_…
• iOS → appl_…

A very common mistake in KMP setups: the shared code hardcodes one key, the test only runs on one platform, and then purchases fail on the other platform once tested. Pass the API key from each platform's entry point so it is obviously correct per target.

App identifiers

Each target's app identifier must be registered in the RevenueCat dashboard:

• iOS bundle identifier → Dashboard → Project → Apps → iOS.
• Android applicationId → Dashboard → Project → Apps → Android.

If you use product flavors or build configurations with different identifiers for dev vs prod, each identifier needs its own dashboard entry or its own RevenueCat project.

Framework build before test

On iOS, KMP produces a framework that the iOS app consumes. After changing shared code, rebuild the framework and pod install (if using CocoaPods) or refresh the SwiftPM package (if using the KMP Swift Package target). Stale frameworks silently run the old configuration.

On Android, a Gradle sync after changing shared code usually suffices.

Sandbox renewal and clearing history

Same as the native platforms:

• iOS accelerated renewal and sandbox tester clearing are documented in ios.md.
• Android accelerated renewal and test clocks are documented in android.md.

Verify per target

On each target:

1. Purchases.logLevel = LogLevel.DEBUG. 2. Native platform console shows the configure banner and the posted transaction. 3. RevenueCat dashboard Sandbox view shows the transaction on the expected appUserID. 4. customerInfo after the purchase shows the expected entitlement active. 5. Restoring purchases on a fresh install brings the entitlement back.

Run these steps on iOS and Android separately. A passing test on one target does not imply the other target is wired correctly.

revenuecat-testing-setup: React Native

react-native-purchases runs against the native iOS and Android SDKs. Testing an RN app means testing each platform against its native testing channel. RN itself does not add a testing mode.

Test Store (RevenueCat synthetic store)

Best for: paywall UI iteration, deterministic purchase outcome scenarios, integration tests, CI smoke runs.

Test Store works on both RN targets. Pass a test_… API key in debug builds and your platform appl_… / goog_… keys in release builds. A single Test Store key from the dashboard covers both targets.

Branch on __DEV__:

import Purchases from 'react-native-purchases';
import { Platform } from 'react-native';

const TEST_KEY = 'test_YOUR_TEST_STORE_KEY';
const PROD_KEY_IOS = 'appl_YOUR_IOS_PRODUCTION_KEY';
const PROD_KEY_ANDROID = 'goog_YOUR_ANDROID_PRODUCTION_KEY';

const apiKey = __DEV__
  ? TEST_KEY
  : Platform.OS === 'ios'
    ? PROD_KEY_IOS
    : PROD_KEY_ANDROID;

Purchases.configure({ apiKey });

For Expo, use eas.json build profiles (development, preview, production) each with its own EXPO_PUBLIC_REVENUECAT_API_KEY environment variable so the key never appears in the JS bundle of the wrong build.

# eas.json
{
  "build": {
    "development": { "env": { "EXPO_PUBLIC_REVENUECAT_API_KEY": "test_YOUR_TEST_STORE_KEY" } },
    "preview":     { "env": { "EXPO_PUBLIC_REVENUECAT_API_KEY": "test_YOUR_TEST_STORE_KEY" } },
    "production":  { "env": { "EXPO_PUBLIC_REVENUECAT_API_KEY": "appl_YOUR_IOS_PRODUCTION_KEY" } }
  }
}

Trigger a purchase. The Test Store dialog opens with Successful Purchase, Failed Purchase, Cancel. Pick an outcome and verify the resulting customerInfo and dashboard transaction.

__DEV__ is false in release builds, so the conditional above keeps the test key out of production binaries via dead code elimination.

Set up each platform

Follow the platform files directly:

• iOS → revenuecat-testing-setup/platforms/ios.md. Prefer a real sandbox Apple ID for RevenueCat dashboard verification.
• Android → revenuecat-testing-setup/platforms/android.md. License tester on the Internal Testing track is required.

Dev client is required (Expo)

Expo Go cannot run react-native-purchases. Any attempt to call the SDK throws a "native module not found" error. Produce a dev client:

npx expo prebuild # bare workflow: generate native projects
# or
eas build --profile development

Install the dev client and reload. Expo Go itself cannot be fixed to support purchase native modules.

Build the right build for each store

iOS

• npx react-native run-ios on a connected device with a sandbox Apple ID works for sandbox testing.
• eas build --profile preview or a standard archive uploaded to TestFlight for TestFlight style testing. TestFlight purchases show on the production dashboard view, not sandbox.

Android

• eas build --profile preview (or cd android && ./gradlew bundleRelease) produces a signed AAB. Upload to Play Internal Testing. Install via the tester opt-in link.
• npx react-native run-android produces a debug build signed with the debug key. Play will not allow sandbox purchases against this signature.

applicationId / bundle identifier must match the dashboard

Every bundle identifier (iOS) or applicationId (Android) that you test must be registered in the RevenueCat dashboard → Project → Apps, with a matching public SDK key.

If you ship multiple environments (dev, staging, prod) with different identifiers, each one needs its own dashboard app entry and its own API key. Branch on Platform.OS and an environment variable (or a build-time constant) to pick the right key.

Platform consoles for logs

Metro's JS console does not show native SDK logs. Watch:

• iOS → Xcode console (when the app is attached) or Console.app filtering by the bundle ID.
• Android → Android Studio Logcat or adb logcat -s Purchases.

Reload does not re-configure the SDK

Purchases.configure(...) runs once per native process launch. Reloading the JS bundle does not re-run native initialization. After changing the API key or purchasesAreCompletedBy, kill the app fully and relaunch.

Metro cache after a dependency change

After bumping react-native-purchases or changing a native build file:

npx react-native start --reset-cache
cd ios && pod install && cd ..
# for Expo:
npx expo prebuild --clean

Stale caches let the JS side bind to an old native module and produce confusing errors.

Verify

1. Purchases.setLogLevel(LOG_LEVEL.DEBUG); before configure. 2. You are running a dev client (not Expo Go), and the Android build is a signed AAB installed from Play Internal Testing. 3. A test purchase succeeds. The native platform console shows the SDK posting the transaction. 4. The RevenueCat dashboard Sandbox view shows the transaction on the expected appUserID. 5. await Purchases.getCustomerInfo() shows the expected entitlement active. 6. Drop log level back to LOG_LEVEL.INFO before shipping.

Run all of those steps on iOS and Android separately.