In-App Purchases skill for Claude Code

Done well means: the server (or RevenueCat) is the source of truth for entitlements, every purchase is verified from signed store data and then finished/acknowledged exactly once, a launch-time listener catches purchases made outside the paywall, renewals, refunds and billing retries arrive via server notifications, and every flow was exercised in sandbox or a StoreKit configuration file before review.

Before changing anything

• Inventory products in both consoles: product IDs, type (consumable, non-consumable, auto-renewable subscription, non-renewing), subscription groups (Apple) and base plans plus offers (Play). Mismatched IDs between code and console are the top “products array is empty” cause.
• Check agreements: Paid Applications agreement, tax and banking in App Store Connect; merchant account in Play Console. Without them products silently do not load.
• Find where entitlement is decided today (a isPro flag in UserDefaults is a bug waiting to happen) and whether a backend account exists to attach purchases to.
• Read the platform rules that matter: digital goods consumed in the app must use store billing; physical goods and person-to-person services must not. External purchase links are region- and program-specific; treat them as a legal decision, not a code one.

Choose the stack

Situation	Use
Subscriptions on iOS + Android, small team, want charts, experiments, webhooks	RevenueCat (or a similar SDK)
iOS only, simple non-consumables, no backend	StoreKit 2 with on-device Transaction.currentEntitlements
Own backend with accounts, strict control, or very high volume	Native StoreKit 2 + Play Billing, server verification, notifications
Web checkout as well as app stores	RevenueCat with web billing or a merchant of record, keyed by your user ID

RevenueCat does not remove the need to understand the store states below; it removes the receipt plumbing. Keep entitlement names (pro) separate from product IDs so prices and durations can change without code changes.

Workflow

- [ ] 1. Products configured in both consoles; IDs listed in one shared constants file
- [ ] 2. Agreements, tax, banking active; license testers / sandbox accounts created
- [ ] 3. Transaction listener started at app launch (before any paywall)
- [ ] 4. Load products, render localized price strings from the store (never hardcode)
- [ ] 5. Purchase with an account token tying it to your user ID
- [ ] 6. Verify (JWS / purchase token) on the server, grant entitlement, then finish/acknowledge
- [ ] 7. Server notifications endpoint (ASSN v2, Play RTDN) updates entitlements
- [ ] 8. Restore purchases button + entitlement refresh on launch and foreground
- [ ] 9. Test matrix: buy, cancel, pending/Ask to Buy, renew, grace, expire, refund, upgrade

StoreKit 2 (iOS 15+, prefer iOS 17+ APIs)

import StoreKit

@MainActor @Observable
final class Store {
    private(set) var products: [Product] = []
    private(set) var activeProductIDs: Set<String> = []
    private var updatesTask: Task<Void, Never>?

    init() {
        // Start at launch: catches renewals, Ask to Buy approvals, offer-code redemptions,
        // purchases from other devices, and anything left unfinished.
        updatesTask = Task { [weak self] in
            for await result in Transaction.updates { await self?.handle(result) }
        }
    }

    func load() async throws {
        products = try await Product.products(for: ProductID.all)
        await refreshEntitlements()
    }

    func buy(_ product: Product, userID: UUID) async throws {
        let result = try await product.purchase(options: [.appAccountToken(userID)])
        switch result {
        case .success(let verification): await handle(verification)
        case .pending: break          // Ask to Buy / SCA: wait for Transaction.updates
        case .userCancelled: break
        @unknown default: break
        }
    }

    private func handle(_ result: VerificationResult<Transaction>) async {
        guard case .verified(let tx) = result else { return }   // never grant unverified
        // Send result.jwsRepresentation to your server here; grant only after it confirms.
        await refreshEntitlements()
        await tx.finish()                                       // finish after granting
    }

    func refreshEntitlements() async {
        var ids: Set<String> = []
        for await case .verified(let tx) in Transaction.currentEntitlements where tx.revocationDate == nil {
            ids.insert(tx.productID)
        }
        activeProductIDs = ids
    }

    func restore() async throws { try await AppStore.sync() }   // only from an explicit button
}

• Transaction.currentEntitlements returns active subscriptions and non-consumables only; consumables never appear. Track consumable balances on your server.
• currentEntitlement(for:) (singular) is deprecated from iOS 18.4; use the plural currentEntitlements(for:) because Family Sharing can yield several transactions.
• SwiftUI offers ProductView, StoreView, and SubscriptionStoreView (iOS 17+) plus .subscriptionStatusTask(for:); use them for fast, review-friendly paywalls.
• AppStore.sync() prompts for the Apple ID password. Call it only from a Restore button; normal launches use currentEntitlements.
• appAccountToken must be a UUID; map your user ID to a stable UUID and store it.
• Offer eligibility: product.subscription?.isEligibleForIntroOffer per group. Do not show “free trial” copy to ineligible users (review rejection and refunds).

Google Play Billing Library 8

val client = BillingClient.newBuilder(context)
    .setListener { billingResult, purchases -> onPurchasesUpdated(billingResult, purchases) }
    .enablePendingPurchases(
        PendingPurchasesParams.newBuilder().enableOneTimeProducts().build()
    )
    .build()

// Query products; v8 returns fetched and unfetched lists separately
val params = QueryProductDetailsParams.newBuilder().setProductList(
    listOf(QueryProductDetailsParams.Product.newBuilder()
        .setProductId("pro_monthly").setProductType(BillingClient.ProductType.SUBS).build())
).build()

// Launch: subscriptions require an offerToken from subscriptionOfferDetails
val flow = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(listOf(
        BillingFlowParams.ProductDetailsParams.newBuilder()
            .setProductDetails(details)
            .setOfferToken(details.subscriptionOfferDetails!!.first().offerToken)
            .build()))
    .setObfuscatedAccountId(hashedUserId)        // ties the purchase to your account
    .build()
client.launchBillingFlow(activity, flow)

Purchase handling rules:

• Only Purchase.PurchaseState.PURCHASED grants access; PENDING (cash, slow payment methods) shows “pending” UI and waits for an update.
• Send purchaseToken to the server, verify with purchases.subscriptionsv2.get or purchases.products.get, grant, then acknowledge. Unacknowledged purchases are refunded automatically after 3 days. Consumables use consumeAsync (which also acknowledges); acknowledge server-side for subscriptions and non-consumables.
• Call queryPurchasesAsync on every app start and resume to recover purchases whose listener callback was missed (process death mid-purchase is common).
• v8 removed queryPurchaseHistoryAsync and querySkuDetailsAsync; purchase history now lives on your backend. Keep the library on the current major: Play blocks app updates that ship a deprecated major after its published deadline.
• Prorations on upgrade/downgrade use SubscriptionUpdateParams with a replacement mode; the new purchase token has linkedPurchaseToken pointing to the old one, so the server must retire the old token.

RevenueCat

Purchases.configure(withAPIKey: "appl_xxx", appUserID: currentUser?.id)  // nil = anonymous
let offerings = try await Purchases.shared.offerings()
let result = try await Purchases.shared.purchase(package: offerings.current!.monthly!)
let isPro = result.customerInfo.entitlements["pro"]?.isActive == true
// On login / logout
let (info, _) = try await Purchases.shared.logIn(user.id)

• Call logIn with your own user ID before purchases whenever accounts exist; anonymous IDs that later alias cause “lost purchase” tickets.
• Use RevenueCat webhooks (or its REST API) for server-side entitlement, not the client.
• Still configure App Store Server Notifications and Play RTDN to point at RevenueCat.

Server side

Verify signed data, never trust the client. For the full ASSN v2 and RTDN state tables, read references/server-verification.md when building or debugging the backend.

Task	Apple	Google
Verify a purchase	Verify JWS (x5c chain to Apple Root CA G3) or call Get Transaction Info	purchases.subscriptionsv2.get / purchases.products.get with a service account
Current subscription state	Get All Subscription Statuses	subscriptionsv2.get (subscriptionState)
Push updates	App Store Server Notifications v2 (signed payload)	RTDN via Cloud Pub/Sub, then fetch state
Refunds	REFUND notification; Get Refund History	Voided Purchases API + VoidedPurchaseNotification
Libraries	App Store Server Library (Swift, Java, Python, Node)	Google API client for Android Publisher

Rules: verifyReceipt is deprecated, do not build on it. Treat notifications as hints: on each one, fetch the current state from the API and upsert. Make handlers idempotent keyed on notificationUUID / Pub/Sub message ID. Store originalTransactionId (Apple) and the latest purchaseToken chain (Google) per user.

Entitlement model

entitlements(user_id, entitlement, source, product_id, store_original_id,
             status, expires_at, grace_until, auto_renew, environment, updated_at)
status ∈ active | grace | billing_retry | expired | revoked | refunded | paused
access = status in (active, grace) and (expires_at > now or grace_until > now)

Separate environment (Sandbox/Production) so sandbox renewals never grant production access. Grace period: keep access, show a “fix payment” banner. Billing retry or account hold: remove access, deep-link to the store’s manage-subscription page.

Gotchas

• Not finishing StoreKit transactions: they redeliver on every launch and block repeat consumable purchases. Finishing before your server granted means a lost purchase.
• Granting from the client in Play without server acknowledge: refunded after 3 days.
• Hardcoded prices or “$4.99” strings: wrong currency, review rejection. Use product.displayPrice / formattedPrice from offer pricing phases.
• Sandbox subscriptions renew on accelerated schedules (minutes); never compare sandbox timing to production in tests of expiry logic.
• Restoring by Apple ID across your accounts: decide the policy (transfer vs. block) for one store account used with two app accounts before launch.
• Missing required paywall content: price, period, auto-renew terms, links to terms and privacy policy. App Review rejects incomplete subscription disclosure.
• Family Sharing and promo/offer codes arrive via Transaction.updates, not via your purchase call. Without a listener they never grant access.

Verification

1. StoreKit configuration file in the Xcode scheme: run purchase, cancel, Ask to Buy (approve/decline in Transaction Manager), refund, renewal and expiry.
2. Sandbox account on device and Play license tester on an internal testing track (Play Billing Lab for faster renewals and region changes).
3. Server: send a test notification (Apple “Request a Test Notification”; Play RTDN test message from Console) and confirm it is logged and idempotent.
4. Check the database after each scenario: one entitlement row per user and product, correct status and expiry, environment set.
5. Kill the app mid-purchase, relaunch, confirm the listener/queryPurchasesAsync path grants and finishes/acknowledges exactly once.