Skip to main content
Pricing, subscriptions, and availability Level: Intermediate 13 min read

StoreKit 2 & RevenueCat Architecture: Anonymous Licensing Verification

How modern iOS applications separate App Store Connect configuration, client-side StoreKit 2 purchases, and anonymous backend receipt verification like RevenueCat, and how FlightDeck dogfoods this architecture.

Published: 2026-11-03 • Last Updated: 2026-11-03 • Author: Kip Lawrence
Key MCP Tools: app_price_schedule_getapp_store_versions_listrelease_readiness_check

Overview: The Three-Tier Monetization Architecture

When building a commercial application for the Apple App Store, developers often conflate three completely separate systems into a single concept called "in-app purchases." This confusion leads to architectural bugs, failed review submissions, and security vulnerabilities.

In production software engineering, modern monetization is structured across three distinct, decoupled tiers:

TEXT
┌────────────────────────────────────────────────────────────────────────┐
│                   THE THREE-TIER MONETIZATION ARCHITECTURE             │
│                                                                        │
│   TIER 1: APP STORE CONNECT METADATA & PRODUCTS                        │
│   [Product IDs, Subscription Groups, Pricing Tiers, Review Screenshots]│
│   • Managed via: App Store Connect Web Portal & FlightDeck MCP         │
│                            │                                           │
│                            ▼                                           │
│   TIER 2: CLIENT APPLICATION STOREKIT 2 ENGINE                         │
│   [Product.products(for:), product.purchase(), JWS Verification]       │
│   • Implemented in: Native Swift, SwiftUI, or Flutter on-device        │
│                            │                                           │
│                            ▼                                           │
│   TIER 3: BACKEND ENTITLEMENT & RECEIPT VERIFICATION                   │
│   [RevenueCat SDK, App Store Server API, Webhook Sync]                 │
│   • Role: Cross-device licensing, restore purchases, churn analysis   │
└────────────────────────────────────────────────────────────────────────┘
  1. Tier 1 (App Store Connect Configuration): Defining product identifiers, subscription groups, price schedules, and review screenshots on Apple's servers.
  2. Tier 2 (Client-Side StoreKit 2): Native on-device Swift code that queries product catalogs, presents paywalls, prompts Face ID / Touch ID payment sheets, and receives signed transaction objects.
  3. Tier 3 (Backend Verification & Entitlement): A backend server or service (such as RevenueCat or a custom App Store Server API service) that verifies transaction cryptograms, tracks subscription lifecycles, and unlocks cross-device features.

FlightDeck itself dogfoods this exact architecture: FlightDeck's desktop macOS application uses StoreKit 2 and RevenueCat to handle its own Pro licensing, while FlightDeck's MCP server manages Tier 1 App Store Connect resources for your applications.


The Primary Licensing Architecture Audit Prompt

Use this prompt with your AI coding assistant (Cursor, Claude Code, Windsurf, or Roo Code) to audit your project's monetization readiness and verify product configuration:

TEXT
Inspect my app [Your App Name] in App Store Connect. Verify the status of all configured in-app purchase and subscription products. List their product identifiers, current approval states, and review screenshot attachments. Audit whether the metadata is ready for client-side StoreKit 2 integration.

Tier 1: App Store Connect Product Configuration

Before any client code can request a product, the product record must exist on Apple's servers:

  • Product Identifier (productId): A permanent reverse-DNS string (e.g. com.example.myapp.pro.annual). Once created, this ID cannot be edited.
  • Product Type: Consumable (coins, credits), Non-Consumable (lifetime unlock), Auto-Renewable Subscription, or Non-Renewing Subscription.
  • Review Details & Screenshot: Apple App Store Review Guideline 2.1 mandates that every IAP or subscription product must have a review screenshot showing the product being used or offered on a physical device. Without this screenshot, Apple will reject the product submission.
  • FlightDeck's Role: FlightDeck MCP tools (release_readiness_check, app_store_versions_list, app_price_schedule_get, and monetization_review_screenshot_upload) orchestrate and audit Tier 1 metadata via Apple's REST API.

Tier 2: Client-Side StoreKit 2 Native Engine

In iOS 15 and macOS 12, Apple introduced StoreKit 2, a modern Swift concurrency-first framework that replaced legacy StoreKit 1 OpenSSL receipt parsing.

StoreKit 2 Architectural Invariants

  1. JSON Web Signatures (JWS): Every purchase transaction is returned as a cryptographically signed JWS string (Transaction.currentEntitlements). The operating system verifies Apple's root certificate signature locally on the device without requiring network calls to your servers.
  2. Simple Asynchronous Purchasing: ```swift import StoreKit

// 1. Fetch products from Apple let products = try await Product.products(for: ["com.example.myapp.pro.annual"]) guard let product = products.first else { return }

// 2. Trigger native Apple purchase sheet let result = try await product.purchase()

// 3. Handle cryptographically verified transaction switch result { case .success(let verification): switch verification { case .verified(let transaction): // Unlock feature locally await transaction.finish() case .unverified(_, let error): print("Cryptographic signature failed: \(error)") } case .userCancelled, .pending: break } ```

  1. Transaction Observer (Transaction.updates): StoreKit 2 automatically listens for background renewal events, refunds, and family sharing revocations across devices.

Tier 3: Backend Entitlement & RevenueCat Integration

While simple apps can rely strictly on on-device StoreKit 2 verification, commercial apps typically require a backend layer for:

  • Synchronizing entitlements across macOS, iOS, Android, and web.
  • Server-to-server webhook notifications for renewals, cancellations, and billing retries.
  • Instant paywall configuration without App Store binary updates.

Credential Partitioning in FlightDeck's Desktop Architecture

FlightDeck Desktop manages its optional Pro subscription using RevenueCat. Code inspection of /Volumes/ext1/code/asc_mcp/apps/flightdeck/lib/src/services/subscription/revenue_cat_subscription_service.dart confirms strict architectural separation between App Store Connect developer credentials and customer licensing:

TEXT
┌────────────────────────────────────────────────────────────────────────┐
│                   FLIGHTDECK CREDENTIAL PARTITIONING MODEL             │
│                                                                        │
│   DEVELOPER SECRETS & KEYS           ANONYMOUS LICENSING TRANSACTIONS  │
│   [App Store Connect API Keys,       [StoreKit Signed JWS Tokens,      │
│    Issuer IDs, .p8 Private Keys]      Anonymous Ephemeral UUIDs]       │
│                │                                   │                   │
│                ▼                                   ▼                   │
│   ┌───────────────────────────┐       ┌────────────────────────────┐   │
│   │  Local macOS Keychain     │       │  RevenueCat Licensing SDK  │   │
│   │  (kSecClassGenericPassword│       │  (purchases_flutter)       │   │
│   └────────────┬──────────────┘       └────────────┬───────────────┘   │
│                │                                   │                   │
│                ▼                                   ▼                   │
│   Apple ASC REST API Directly         RevenueCat Licensing API         │
│   (https://api.appstoreconnect.apple) (https://api.revenuecat.com)     │
└────────────────────────────────────────────────────────────────────────┘
  1. Credential Isolation: RevenueCat never receives your App Store Connect API keys, Issuer IDs, or .p8 private keys. Those credentials reside exclusively in your local macOS Keychain (asc:mcp:api_key) and are transmitted only to Apple's authoritative API endpoint (api.appstoreconnect.apple.com).
  2. Anonymous Licensing Identity: In FlightDeck Desktop, RevenueCat is initialized with appUserID: null, ensuring customer status is tracked anonymously without linking to your Apple Developer Account identity.
  3. Encapsulated Licensing Logic: FlightDeck's RevenueCatSubscriptionService strictly isolates purchase types. Active entitlements control feature gates, while product metadata remains presentation-only.

Architectural Separation: Implementation vs. Recommendations

To evaluate monetization architecture clearly, distinguish between what FlightDeck implements, what external services provide, and what general patterns apply:

Implemented in FlightDeck Desktop (Verified Codebase)

  • Framework: Native Flutter macOS desktop application using the purchases_flutter plugin.
  • Credential Storage: Hardware-backed macOS Keychain storage for ASC credentials (.p8, Key ID, Issuer ID) completely isolated from RevenueCat SDK.
  • Customer Identity: Anonymous UUID allocation (appUserID = null) for desktop licensing.
  • Entitlement Handling: Local stream-based resolution (RevenueCatSubscriptionService) managing active entitlement caching and automatic reconciliation on ambiguous store errors.

General Architectural Patterns (For Your Own Applications)

  • Direct Swift StoreKit 2: For native iOS/macOS apps written in Swift, implementing direct Product.purchase() and Transaction.currentEntitlements calls without third-party frameworks.
  • Server Notifications V2: Implementing webhooks from App Store Connect to your cloud backend (or RevenueCat) to handle background subscription renewals, cancellations, and billing retries. FlightDeck Desktop does not host an App Store webhook receiver for your apps.

External Service Behavior (Apple & RevenueCat)

  • Apple StoreKit & Server API: Authoritative generation of signed JWS transactions and App Store Server Notifications V2.
  • RevenueCat Backend: Server-side receipt parsing, cross-platform entitlement synchronization, and webhook routing.

What FlightDeck Can and Cannot Do

To avoid confusion when pairing AI assistants with your codebase:

What FlightDeck MCP Can Do

  1. Audit Product Readiness: Check that subscription groups and IAP items in App Store Connect have valid localizations, price points, and review notes.
  2. Inspect Price Schedules: Call app_price_schedule_get to verify live base pricing.
  3. Stage Review Screenshots: Upload required App Review proof screenshots via monetization_review_screenshot_upload so your IAPs are eligible for submission.
  4. Detect Preflight Blockers: Call release_readiness_check to ensure no draft products stall your app release.

What Must Be Built in Your Codebase (Client & Backend)

  1. StoreKit 2 Swift Code: FlightDeck MCP cannot compile Swift files, instantiate StoreKit.Product, or render your in-app paywall view. That code belongs in your Xcode / Flutter repository.
  2. Backend Server Notification Handlers: Apple's App Store Server Notifications V2 must be handled by your web backend or a service like RevenueCat.

Step-by-Step Architecture Checklist

When shipping an app with In-App Purchases, follow this verification checklist:

  1. Configure Products in App Store Connect (Tier 1): - Create the Product ID in App Store Connect. - Assign a Reference Name and localized Display Title. - Configure a Base Price Schedule in USA territory. - Upload a representative review screenshot.
  2. Implement StoreKit 2 in Client App (Tier 2): - Query products using Product.products(for:). - Verify transaction authenticity via verification.verified. - Call await transaction.finish() once the digital good or entitlement is granted.
  3. Connect Backend Verification (Tier 3): - If using RevenueCat, initialize with your public SDK key (appl_...). - Configure App Store Server Notifications in App Store Connect under App Information > App Store Server Notifications pointing to your webhook URL.
  4. Test in Sandbox Environment: - Use Xcode StoreKit Configuration files (.storekit) for local unit tests without network calls. - Use App Store Connect Sandbox Tester accounts on physical iOS devices to test real renewal intervals (1-month subscription renews every 5 minutes in Sandbox).

Common Errors & Troubleshooting

1. StoreKit 2 returns empty array for Product.products(for:)

  • Cause: Product ID typo, Paid Applications Agreement unaccepted in App Store Connect, or products created recently and still propagating across Apple's edge cache (can take up to 2 hours).
  • Fix: Confirm the Paid Applications Agreement is active in App Store Connect > Business, verify exact bundle ID matching, and allow propagation time.

2. Transaction Failed: Cannot connect to iTunes Store

  • Cause: Testing on a simulator without an active .storekit configuration file, or network disruption to Apple Sandbox servers.
  • Fix: In Xcode, go to Product > Scheme > Edit Scheme > Run > Options and assign a local .storekit configuration file for offline testing.

3. RevenueCat / Backend reports "Missing App Store Server Notifications"

  • Cause: In-app purchases work, but subscription cancellations and renewals fail to sync.
  • Fix: In App Store Connect under General > App Information, paste your backend's Server Notifications V2 URL and generate an App Store Server API private key for status polling.


Official References


Evidence Limitations & Verifications

  • Codebase Source Inspection: FlightDeck's licensing model is verified directly against /Volumes/ext1/code/asc_mcp/apps/flightdeck/lib/src/services/subscription/revenue_cat_subscription_service.dart.
  • Credential Isolation Invariant: Verified that FlightDeck's Keychain storage (asc:mcp:api_key) is completely partitioned from the RevenueCat configuration (PurchasesConfiguration).
  • Implementation Scope: FlightDeck MCP tools validate and stage App Store Connect resources; they do not write native client Swift code or execute in-app purchases.

Connect Your AI Agent to App Store Connect

FlightDeck runs locally on your Mac, keeping private keys secure in your macOS Keychain and executing mutations only after your explicit approval.

Download FlightDeck on Mac App Store