RevenueCat

In-app purchases, subscriptions, and paywalls on iOS via RevenueCat's Purchases SDK and RevenueCatUI. RevenueCat sits on top of StoreKit: it owns product fetching, the purchase flow, the entitlement computation, and (optionally) the paywall UI. The full API reference — SDK configuration, offerings/packages, the purchase flow, CustomerInfo entitlements, restore, and RevenueCatUI paywalls — lives in references/guide.md; a focused troubleshooting note for the iOS 26 PaywallView "Missing Metadata" failure is in references/ios26-paywall-fix.md. This file is the decision and discipline layer: read it first, open the references for specifics.

Dials

Set these explicitly at the start; they change what "correct" means.

1. PAYWALL_UI — revenuecatui-prebuilt (default; RevenueCatUI PaywallView / presentPaywallIfNeeded, templates configured in the dashboard) · custom (you read offering.availablePackages and build your own merchandising; you own card layout, pricing copy, and selection state).
2. ENTITLEMENT_MODE — entitlement-id (default; gate features on customerInfo.entitlements["pro"]?.isActive, identifier configured in the RevenueCat dashboard) · product-id (check activeSubscriptions / nonSubscriptionTransactions directly — only when you deliberately bypass entitlements).
3. STOREKIT_VERSION — sk2 (default; RevenueCat's StoreKit 2 backend, required for current iOS targets) · sk1 (legacy fallback). This is RevenueCat's internal StoreKit layer, not your code — you do not call StoreKit directly.

When to use

Building or reviewing any purchase, paywall, subscription, restore, or entitlement-gating code that goes through RevenueCat's Purchases SDK or RevenueCatUI. If the app talks to StoreKit/Transaction directly instead of RevenueCat, use the storekit skill. Do not run both: pick RevenueCat as the source of truth and let it wrap StoreKit, or use StoreKit alone — two entitlement systems will disagree.

Core rules