RevenueCat SDK Integration
for Agent Developers

This guide exists because the RevenueCat docs are written for humans who read linearly and click between pages. Agents need something different: a single-page reference with verified code patterns, explicit gotchas, and the mental model that connects Products → Entitlements → Offerings → Packages into a working subscription system.

Everything here is sourced from RevenueCat's official documentation. Where I reference specific SDK methods or API behavior, I've verified the signatures and semantics directly. No fabricated methods. No invented parameters.

The mental model

RevenueCat's architecture has three layers of abstraction, and understanding them prevents the most common integration mistakes:

The critical insight: a product must be attached to an entitlement for the purchase to grant access. The purchase will succeed at the store level regardless — money leaves the user's account — but the SDK's entitlement check will return false if this wiring is missing. This is the #1 RevenueCat debugging issue (see the troubleshooting guide).

A single product can unlock multiple entitlements, and multiple products can unlock the same entitlement. Most apps have one entitlement ("pro") unlocked by multiple products (monthly, annual, lifetime).

1. SDK configuration

Configure once, early in the app lifecycle. Use only the public API key (found in Project Settings → API keys → App specific keys). Never use secret keys in client code.

// In application(_:didFinishLaunchingWithOptions:)
// or SwiftUI App.init()
Purchases.logLevel = .debug
Purchases.configure(
  withAPIKey: "<public_apple_api_key>",
  appUserID: <app_user_id> // nil for anonymous
)

// In Application.onCreate()
Purchases.logLevel = LogLevel.DEBUG
Purchases.configure(
  PurchasesConfiguration.Builder(this, "<public_google_api_key>")
    .build()
)

import Purchases, { LOG_LEVEL } from 'react-native-purchases';

// In useEffect on app mount
// Note: React Native uses VERBOSE; Swift/Kotlin use .debug/DEBUG
Purchases.setLogLevel(LOG_LEVEL.VERBOSE);
if (Platform.OS === 'ios') {
  Purchases.configure({ apiKey: "<public_apple_api_key>" });
} else if (Platform.OS === 'android') {
  Purchases.configure({ apiKey: "<public_google_api_key>" });
}

await Purchases.setLogLevel(LogLevel.debug);

PurchasesConfiguration configuration;
if (Platform.isAndroid) {
  configuration = PurchasesConfiguration("<public_google_api_key>");
} else if (Platform.isIOS) {
  configuration = PurchasesConfiguration("<public_apple_api_key>");
}
await Purchases.configure(configuration);

2. User identity

RevenueCat identifies users via an appUserID. If you don't provide one at configuration, RevenueCat generates an anonymous ID (prefixed with $RCAnonymousID:) and caches it on device. Anonymous IDs work for single-platform apps, but can't share subscription status across platforms.

// Configure without user ID first
Purchases.configure(withAPIKey: "<api_key>")

// Later, when user authenticates:
Purchases.shared.logIn("<my_app_user_id>") { (customerInfo, created, error) in
  // customerInfo is now for the identified user
  // 'created' indicates if this is a new RC customer
}

// Generates a new anonymous ID
Purchases.shared.logOut { (customerInfo, error) in
  // Now on a fresh anonymous user
}

When switching accounts, you can call .logIn() directly with the new ID — no need to .logOut() first.

3. Fetching offerings & displaying products

Offerings are fetched through the SDK and are pre-fetched on app launch in most cases. The current offering is whatever's set as default in the dashboard (or what Targeting/Experiments assigns to that customer).

Purchases.shared.getOfferings { (offerings, error) in
  if let packages = offerings?.current?.availablePackages {
    // Display packages — each has:
    //   .storeProduct (price, duration, metadata)
    //   .packageType (.monthly, .annual, .lifetime, etc.)
    //   .identifier
  }
}

// Access specific package types directly:
let monthly = offerings?.current?.monthly
let annual = offerings?.current?.annual

// Or by custom identifier:
let custom = offerings?.current?.package(identifier: "<package_id>")

const offerings = await Purchases.getOfferings();
if (
  offerings.current !== null &&
  offerings.current.availablePackages.length !== 0
) {
  // offerings.current.availablePackages
  // offerings.current.monthly
  // offerings.current.annual
}

Package types abstract platform-specific products. A monthly package on iOS maps to an App Store product; the same monthly package on Android maps to a Play Store product. Your paywall code references packages, not product IDs — this is what makes offerings remotely configurable without app updates.

4. Making purchases

The SDK has a single method for purchases across all platforms: purchase(package:). It takes a package from the fetched offering and handles the entire store transaction.

Purchases.shared.purchase(package: package) { (transaction, customerInfo, error, userCancelled) in
  if customerInfo.entitlements["your_entitlement_id"]?.isActive == true {
    // Unlock premium content
  }
}

Purchases.sharedInstance.purchaseWith(
  PurchaseParams.Builder(this, aPackage).build(),
  onError = { error, userCancelled -> /* No purchase */ },
  onSuccess = { storeTransaction, customerInfo ->
    if (customerInfo.entitlements["my_entitlement_identifier"]?.isActive == true) {
      // Unlock premium content
    }
  }
)

try {
  const { customerInfo } = await Purchases.purchasePackage(package);
  if (
    typeof customerInfo.entitlements.active["my_entitlement_identifier"]
      !== "undefined"
  ) {
    // Unlock premium content
  }
} catch (e) {
  if (!e.userCancelled) {
    showError(e);
  }
}

try {
  final purchaseParams = PurchaseParams.package(package);
  PurchaseResult result = await Purchases.purchase(purchaseParams);
  if (result.customerInfo.entitlements.all["my_entitlement_identifier"]
      ?.isActive ?? false) {
    // Unlock premium content
  }
} on PlatformException catch (e) {
  var errorCode = PurchasesErrorHelper.getErrorCode(e);
  if (errorCode != PurchasesErrorCode.purchaseCancelledError) {
    showError(e);
  }
}

The completion block returns an updated CustomerInfo object. Check entitlements here — not product identifiers. The entitlement is the source of truth for access.

RevenueCat automatically finishes/acknowledges transactions by default. If you're migrating from existing purchase logic and want to handle completion yourself, set purchasesCompletedBy to your app during configuration. But for new integrations, leave the default — the SDK handles it.

The SDK also supports Offline Entitlements — when RevenueCat servers are unreachable, the SDK can verify Apple/Google purchases on-device and grant entitlements temporarily. This happens automatically for new integrations using the default purchasesCompletedBy setting. Offline Entitlements are disabled when your app is completing transactions itself (i.e., purchasesCompletedBy set to your app). No information is lost — all purchases are recorded and processed once servers are back online.

5. Checking entitlement status

The CustomerInfo object is the central source of truth. It's updated on every purchase, restore, and periodically throughout the app lifecycle. The SDK caches it — calls to getCustomerInfo() usually pull from cache and are fast. Call it freely wherever you need to gate content.

// Swift Concurrency
let customerInfo = try await Purchases.shared.customerInfo()
if customerInfo.entitlements.all["pro"]?.isActive == true {
  // User has "pro" access
}

// Or with completion block:
Purchases.shared.getCustomerInfo { (customerInfo, error) in
  if customerInfo?.entitlements.all["pro"]?.isActive == true {
    // User has "pro" access
  }
}

const customerInfo = await Purchases.getCustomerInfo();
if (
  typeof customerInfo.entitlements.active["pro"] !== "undefined"
) {
  // User has "pro" access
}

Key properties on EntitlementInfo:

isActive          → Is the entitlement currently active?
willRenew         → Is the subscription set to renew?
periodType        → Trial | Intro | Promotional | Normal
latestPurchaseDate → Most recent purchase or renewal
expirationDate    → When access expires (null = lifetime)
store             → appStore | playStore | amazon | stripe | promotional
unsubscribeDetectedAt → Date unsubscribe detected (null if active)
billingIssueDetectedAt → Date billing issue detected (null if none)

6. Listening for updates & restoring purchases

You can react to subscription changes in real-time via a delegate (iOS) or listener (Android/cross-platform). This fires on any CustomerInfo change from the current device.

Purchases.shared.delegate = self

extension AppDelegate: PurchasesDelegate {
  func purchases(_ purchases: Purchases,
                 receivedUpdated customerInfo: CustomerInfo) {
    // Handle any changes to customerInfo
  }
}

// Or with Swift Concurrency:
for try await customerInfo in Purchases.shared.customerInfoStream {
  // Handle changes
}

Purchases.addCustomerInfoUpdateListener((info) => {
  // Handle any changes to customerInfo
});

Restoring purchases re-syncs transactions from the same store account. Apple requires a restore mechanism in your app. RevenueCat Paywalls include a built-in restore button by default.

Purchases.shared.restorePurchases { customerInfo, error in
  // Check customerInfo to see if entitlement is now active
}

7. MCP server integration for automated setup

RevenueCat's MCP server at https://mcp.revenuecat.ai/mcp provides 26 tools for managing subscriptions via natural language. An agent can configure the entire backend — apps, products, entitlements, offerings, packages, paywalls — without touching the dashboard. Authentication uses a Bearer token with a v2 API key.

The agent workflow: an agent uses the MCP server to create the backend configuration, then generates SDK integration code using the actual identifiers from that configuration. This eliminates the most error-prone step — manually copying product IDs and entitlement names between the dashboard and code.

For a detailed analysis of the MCP server's 26 tools and what's missing, see the MCP Analysis.

8. Testing

RevenueCat's Test Store lets you validate the entire purchase flow without sandbox accounts or store credentials. It ships with every new project and works immediately.

9. The five silent failures

These are the integration mistakes that don't throw errors — they just silently break the subscription flow. An agent generating RevenueCat integration code should validate against all five.

Quick reference

Configure
  Swift:  Purchases.configure(withAPIKey:appUserID:)
  Kotlin: Purchases.configure(PurchasesConfiguration.Builder(...).build())
  RN:     Purchases.configure({ apiKey })
  Flutter: Purchases.configure(PurchasesConfiguration(...))

Login / Identity
  Swift:  Purchases.shared.logIn("id") { customerInfo, created, error in }
  Kotlin: Purchases.sharedInstance.logIn("id") { customerInfo, created -> }
  RN:     await Purchases.logIn("id")
  Flutter: await Purchases.logIn("id")

Get Offerings
  Swift:  Purchases.shared.getOfferings { offerings, error in }
  Kotlin: Purchases.sharedInstance.getOfferings(onSuccess = { }, onError = { })
  RN:     await Purchases.getOfferings()
  Flutter: await Purchases.getOfferings()

Purchase
  Swift:  Purchases.shared.purchase(package:) { txn, info, error, cancelled in }
  Kotlin: Purchases.sharedInstance.purchaseWith(PurchaseParams.Builder(...))
  RN:     await Purchases.purchasePackage(package)
  Flutter: await Purchases.purchase(PurchaseParams.package(package))

Check Entitlements
  Swift:  try await Purchases.shared.customerInfo()
          Purchases.shared.getCustomerInfo { info, error in }
  Kotlin: Purchases.sharedInstance.getCustomerInfo(onSuccess = { }, onError = { })
  RN:     await Purchases.getCustomerInfo()
  Flutter: await Purchases.getCustomerInfo()

Restore
  Swift:  Purchases.shared.restorePurchases { info, error in }
  Kotlin: Purchases.sharedInstance.restorePurchases(onSuccess = { }, onError = { })
  RN:     await Purchases.restorePurchases()
  Flutter: await Purchases.restorePurchases()

Listener
  Swift:  Purchases.shared.delegate / customerInfoStream
  Kotlin: Purchases.sharedInstance.updatedCustomerInfoListener
  RN:     Purchases.addCustomerInfoUpdateListener(callback)
  Flutter: Purchases.addCustomerInfoUpdateListener(callback)