axiom-in-app-purchases

StoreKit 2 In-App Purchase Implementation

Purpose: Guide robust, testable in-app purchase implementation StoreKit Version: StoreKit 2 iOS Version: iOS 15+ (iOS 18.4+ for latest features) Xcode: Xcode 13+ (Xcode 16+ recommended) Context: WWDC 2025-241, 2025-249, 2023-10013, 2021-10114

When to Use This Skill

✅ Use this skill when:

• Implementing any in-app purchase functionality (new or existing)
• Adding consumable products (coins, hints, boosts)
• Adding non-consumable products (premium features, level packs)
• Adding auto-renewable subscriptions (monthly/annual plans)
• Debugging purchase failures, missing transactions, or restore issues
• Setting up StoreKit testing configuration
• Implementing subscription status tracking
• Adding promotional offers or introductory offers
• Server-side receipt validation
• Family Sharing support

❌ Do NOT use this skill for:

• StoreKit 1 (legacy API) - this skill focuses on StoreKit 2
• App Store Connect product configuration (separate documentation)
• Pricing strategy or business model decisions

---

⚠️ Already Wrote Code Before Creating .storekit Config?

If you wrote purchase code before creating .storekit configuration, you have three options:

Option A: Delete and Start Over (Strongly Recommended)

Delete all IAP code and follow the testing-first workflow below. This reinforces correct habits and ensures you experience the full benefit of .storekit-first development.

Why this is best:

• Validates that you understand the workflow
• Catches product ID issues you might have missed
• Builds muscle memory for future IAP implementations
• Takes only 15-30 minutes for experienced developers

Option B: Create .storekit Config Now (Acceptable with Caution)

Create the .storekit file now with your existing product IDs. Test everything works locally. Document in your PR that you tested in sandbox first.

Trade-offs:

• ✅ Keeps working code
• ✅ Adds local testing capability
• ❌ Misses product ID validation benefit
• ❌ Reinforces testing-after pattern
• ❌ Requires extra vigilance in code review

If choosing this path: Create .storekit immediately, verify locally, and commit a note explaining the approach.

Option C: Skip .storekit Entirely (Not Recommended)

Commit without .storekit configuration, test only in sandbox.

Why this is problematic:

• Teammates can't test purchases locally
• No validation of product IDs before runtime
• Harder iteration (requires App Store Connect)
• Missing documentation of product structure

Bottom line: Choose Option A if possible, Option B if pragmatic, never Option C.

---

Core Philosophy: Testing-First Workflow

Best Practice: Create and test StoreKit configuration BEFORE writing production purchase code.

Why .storekit-First Matters

The recommended workflow is to create .storekit configuration before writing any purchase code. This isn't arbitrary - it provides concrete benefits:

Immediate product ID validation:

• Typos caught in Xcode, not at runtime
• Product configuration visible in project
• No App Store Connect dependency for testing

Faster iteration:

• Test purchases in simulator instantly
• No network requests during development
• Accelerated subscription renewal for testing

Team benefits:

• Anyone can test purchase flows locally
• Product catalog documented in code
• Code review includes purchase testing

Common objections addressed:

❓ "I already tested in sandbox" - Sandbox testing is valuable but comes later. Local testing with .storekit is faster and enables true TDD.

❓ "My code works" - Working code is great! Adding .storekit makes it easier for teammates to verify and maintain.

❓ "I've done this before" - Experience is valuable. The .storekit-first workflow makes experienced developers even more productive.

❓ "Time pressure" - Creating .storekit takes 10-15 minutes. The time saved in iteration pays back immediately.

The Recommended Workflow

StoreKit Config → Local Testing → Production Code → Unit Tests → Sandbox Testing
      ↓               ↓                ↓               ↓              ↓
   .storekit      Test purchases   StoreManager    Mock store    Integration test

Why this order helps:

1. StoreKit Config First: Defines products without App Store Connect dependency
2. Local Testing: Validates product IDs and purchase flows immediately
3. Production Code: Implements against validated product configuration
4. Unit Tests: Verifies business logic with mocked store responses
5. Sandbox Testing: Final validation in App Store environment

Benefits of following this workflow:

• Product IDs validated before writing code
• Faster development iteration
• Easier team collaboration
• Better test coverage

---

Mandatory Checklist

Before marking IAP implementation complete, ALL items must be verified:

Phase 1: Testing Foundation

• Created .storekit configuration file with all products
• Verified each product type renders correctly in StoreKit preview
• Tested successful purchase flow for each product in Xcode
• Tested purchase failure scenarios (insufficient funds, cancelled)
• Tested restore purchases flow
• For subscriptions: tested renewal, expiration, and upgrade/downgrade

Phase 2: Architecture

• Centralized StoreManager class exists (single source of truth)
• StoreManager is ObservableObject (SwiftUI) or uses NotificationCenter
• Transaction observer listens for updates via Transaction.updates
• All transaction verification uses VerificationResult
• All transactions call .finish() after entitlement granted
• Product loading happens at app launch or before displaying store

Phase 3: Purchase Flow

• Purchase uses new purchase(confirmIn:options:) with UI context (iOS 18.2+)
• Purchase handles all PurchaseResult cases (success, userCancelled, pending)
• Purchase verifies transaction signature before granting entitlement
• Purchase stores transaction receipt/identifier for support
• appAccountToken set for all purchases (if using server backend)

Phase 4: Subscription Management (if applicable)

• Subscription status tracked via Product.SubscriptionInfo.Status
• Current entitlements checked via Transaction.currentEntitlements(for:)
• Renewal info accessed for expiration, renewal date, offer status
• Subscription views use ProductView or SubscriptionStoreView
• Win-back offers implemented for expired subscriptions
• Grace period and billing retry states handled

Phase 5: Restore & Sync

• Restore purchases implemented (required by App Store Review)
• Restore uses Transaction.currentEntitlements or Transaction.all
• Family Sharing transactions identified (if supported)
• Server sync implemented (if using backend)
• Cross-device entitlement sync tested

Phase 6: Error Handling

• Network errors handled gracefully (retries, user messaging)
• Invalid product IDs detected and logged
• Purchase failures show user-friendly error messages
• Transaction verification failures logged and reported
• Refund notifications handled (via App Store Server Notifications)

Phase 7: Testing & Validation

• Unit tests verify purchase logic with mocked Product/Transaction
• Unit tests verify subscription status determination
• Integration tests with StoreKit configuration pass
• Sandbox testing with real Apple ID completed
• TestFlight testing completed before production release

---

Step 1: Create StoreKit Configuration (FIRST!)

DO THIS BEFORE WRITING ANY PURCHASE CODE.

Create Configuration File

1. Xcode → File → New → File → StoreKit Configuration File
2. Save as: Products.storekit (or your app name)
3. Add to target: ✅ (include in app bundle for testing)

Add Products

Click "+" and add each product type:

Consumable

Product ID: com.yourapp.coins_100
Reference Name: 100 Coins
Price: $0.99

Non-Consumable

Product ID: com.yourapp.premium
Reference Name: Premium Upgrade
Price: $4.99

Auto-Renewable Subscription

Product ID: com.yourapp.pro_monthly
Reference Name: Pro Monthly
Price: $9.99/month
Subscription Group ID: pro_tier

Test Immediately

1. Run app in simulator
2. Scheme → Edit Scheme → Run → Options
3. StoreKit Configuration: Select Products.storekit
4. Verify: Products load, purchases complete, transactions appear

---

Step 2: Implement StoreManager Architecture

Required Pattern: Centralized StoreManager

All purchase logic must go through a single StoreManager. No scattered Product.purchase() calls throughout app.

import StoreKit

@MainActor
final class StoreManager: ObservableObject {
    // Published state for UI
    @Published private(set) var products: [Product] = []
    @Published private(set) var purchasedProductIDs: Set<String> = []

    // Product IDs from StoreKit configuration
    private let productIDs = [
        "com.yourapp.coins_100",
        "com.yourapp.premium",
        "com.yourapp.pro_monthly"
    ]

    private var transactionListener: Task<Void, Never>?

    init() {
        // Start transaction listener immediately
        transactionListener = listenForTransactions()

        Task {
            await loadProducts()
            await updatePurchasedProducts()
        }
    }

    deinit {
        transactionListener?.cancel()
    }
}

Why @MainActor: Published properties must update on main thread for UI binding.

Load Products (At Launch)

extension StoreManager {
    func loadProducts() async {
        do {
            // Load products from App Store
            let loadedProducts = try await Product.products(for: productIDs)

            // Update published property on main thread
            self.products = loadedPro

---

*Content truncated.*