In-App Purchases skill for Codex

Done well means: the server, not the device, decides what a user is entitled to; every purchase is verified, acknowledged or finished exactly once; renewals, refunds and billing failures reach the server by notification within minutes; and prices shown are the store’s localized strings, never hard-coded.

Store rules on what must use in-app purchase, external purchase links and regional exceptions (US anti-steering rulings, EU DMA terms) change often. Check the current App Review Guidelines and Play payments policy, and have the client’s lawyer confirm anything outside the default IAP path.

Before changing anything

1. Read AGENTS.md, then find existing billing code, the entitlement model on the server, and whether RevenueCat, Adapty or another SDK is already present.
2. Write the product catalog: product IDs, type (consumable, non-consumable, auto-renewable subscription, non-renewing), subscription groups and base plans/offers, and the entitlement each one grants (pro, credits, ad_free).
3. Confirm accounts: the app’s user ID, how it maps to store transactions (appAccountToken on iOS, obfuscatedAccountId on Android), and what happens for purchases made while logged out.
4. Creating products, prices and offers in App Store Connect or Play Console changes what real customers pay. Draft them and ask the user to confirm before creating or editing.

Build or buy

Situation	Choice
Subscriptions on both platforms, small team, want analytics and paywall experiments	RevenueCat (or similar): it runs receipt validation, webhooks and entitlement state
Existing backend with user accounts, need full data ownership	Native StoreKit 2 + Play Billing, server verification described below
A single non-consumable purchase on iOS	StoreKit 2 on device with Transaction.currentEntitlements; server optional

With RevenueCat, still log in with your own user ID (Purchases.logIn), gate features on customerInfo.entitlements["pro"]?.isActive, and consume its webhooks on the server.

iOS: StoreKit 2

@MainActor
final class Store: ObservableObject {
    private var updates: Task<Void, Never>?

    init() {
        updates = Task { for await result in Transaction.updates { await self.handle(result) } }
    }

    func buy(_ product: Product, userID: UUID) async throws {
        switch try await product.purchase(options: [.appAccountToken(userID)]) {
        case .success(let result): await handle(result)
        case .pending: break                  // Ask to Buy or 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
        await sendToServer(jws: result.jwsRepresentation)        // server grants entitlement
        await tx.finish()                                        // only after it is recorded
    }
}

• Start the Transaction.updates listener at launch, before any UI; renewals, Ask to Buy approvals and purchases from other devices arrive there.
• Load products with try await Product.products(for: ids) and show product.displayPrice.
• Restore: try await AppStore.sync() only behind an explicit “Restore Purchases” button (it may prompt for the Apple Account password). Read state from Transaction.currentEntitlements.
• Subscription status: product.subscription?.status gives renewal state and grace period.
• verifyReceipt and the app receipt are deprecated; send the transaction JWS to the server and verify it with Apple’s App Store Server Library.

Android: Play Billing Library

Keep the library current; Play requires a recent major version for new apps and updates (check the deprecation schedule in the Play Billing release notes).

1. Build BillingClient with a PurchasesUpdatedListener and enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build()).
2. startConnection; on disconnect, reconnect with backoff before the next call.
3. queryProductDetailsAsync for the product IDs; for subscriptions pick an offerToken from subscriptionOfferDetails.
4. launchBillingFlow with ProductDetailsParams and setObfuscatedAccountId(hash(userId)).
5. In the listener and on every app start (queryPurchasesAsync), for each purchase with purchaseState == PURCHASED: send purchaseToken to the server, which verifies it and then acknowledges (acknowledge API or consumeAsync for consumables).
6. PENDING purchases grant nothing until they move to PURCHASED.

Unacknowledged purchases are refunded automatically after three days. Acknowledge from the server (Developer API) or the client, but only after the entitlement is stored.

Server: source of truth

Task	Apple	Google
Verify a purchase	Verify the signed transaction JWS (App Store Server Library)	purchases.products.get / purchases.subscriptionsv2.get
Current subscription state	App Store Server API Get All Subscription Statuses	purchases.subscriptionsv2.get
Change events	App Store Server Notifications V2 (signed payload)	Real-time Developer Notifications via Cloud Pub/Sub
Refunds / revocations	REFUND, REVOKE notifications	voidedPurchaseNotification, Voided Purchases API

Pattern for every notification: verify its signature or Pub/Sub auth, dedupe by notification ID, then re-fetch the current state from the store API and recompute the entitlement. Do not apply incremental state from the notification alone; they can arrive late, twice or out of order.

For the notification types that matter and how each maps to entitlement changes, read references/store-notifications.md when building the webhook handler.

Entitlement row shape:

entitlement(user_id, key, source[apple|google|promo], original_transaction_id | purchase_token,
            product_id, status[active|grace|billing_retry|expired|revoked], expires_at, updated_at)

Testing

• iOS local: a .storekit configuration file in the Xcode scheme; test renewals at accelerated rates, Ask to Buy, refunds and billing failures from Xcode’s transaction manager. Unit-test with SKTestSession.
• iOS sandbox: Sandbox Apple Accounts; TestFlight builds also use sandbox.
• Android: license testers in Play Console, test cards that always approve, decline or stay pending; the app must be uploaded to a testing track with the matching application ID and signed build.
• Send a test notification: App Store Server API Request a Test Notification; Play Console’s RTDN “Send test notification”.

Gotchas

• Finishing (iOS) or acknowledging (Android) before the server has stored the entitlement loses the purchase if the app dies in between.
• Family Sharing and promo codes create transactions the app never initiated; they arrive through Transaction.updates and notifications only.
• Upgrades and downgrades within a subscription group change the product without a new original transaction; key entitlements on the original transaction ID.
• Do not block app launch on the store being reachable; cache the last known entitlement with its expiry and refresh in the background.
• Account deletion: tell users that store subscriptions must be cancelled in store settings, and link to the store’s subscription management page.

Verification

• New purchase, renewal, cancellation, expiry, billing retry and refund each change the server entitlement correctly (sandbox or test notifications)
• Killing the app between purchase and server call recovers on next launch
• Restore on a fresh install and on a second device grants the same entitlement
• Pending purchase grants nothing until approved
• Prices render from store data in at least two locales

Output

**Catalog:** <product id -> type, entitlement>
**Client:** <StoreKit 2 / Play Billing / RevenueCat, listener at launch, restore path>
**Server:** <verification, notifications endpoint, state recompute>
**Tested:** <scenario -> result, environment>