Game IAP

Purchases are the part of a game most likely to lose real money to a bug, and the part least covered by tests because the store is remote and asynchronous. This skill gives the architecture that makes IAP testable, the platform APIs, and the policy rules that cause rejection.

Decide first

Answer these three before writing code. They determine everything else.

Never gate content on a network call at launch. A player who paid and boarded a plane must still have their content.

Core architecture

One interface, three implementations. This is the whole trick — it makes IAP unit-testable without a store, and it is what lets you ship a desktop or web build that simply sells nothing.

StoreBackend (interface, async via callbacks/signals)
├── PlayBillingBackend    — Android
├── StoreKitBackend       — iOS
├── FakeStoreBackend      — tests, debug builds, screenshots
└── NullBackend           — platforms where you do not sell (desktop, web)

The interface needs exactly five outbound events and four inbound calls:

events:  purchase_finished(sku, success, error)
         purchases_synced(owned_skus[])      # the store's complete list
         sync_failed(error)                  # offline — do NOT clear entitlements
         prices_loaded({sku: localized_price})
         availability_changed(available)

calls:   start()          # connect, then immediately sync + load prices
         purchase(sku)
         restore()        # re-query owned products
         is_available()

purchases_synced carrying the complete list (not a delta) is what makes refunds work: when the store answers, it replaces local state rather than merging into it.

Full worked implementation, including the reconciliation edge cases: references/reference-implementation-godot.md

Product catalog as data

Keep products in a data file (JSON), not in code, with: id, display name key, description key, type, fallback price, and what it unlocks. Then:

• is_covered(sku) answers "does the player already have this?" including bundles — a supporter_bundle must cover full_unlock, which must cover grade_2..grade_5. Without a coverage rule you will sell someone content they already own.
• The store, the paywall UI and the tests all read the same list, so a typo shows up once.

Product IDs are permanent. Google Play and Apple both refuse to reuse an ID after it exists, even deleted. Decide the naming scheme before creating the first one. Lowercase, underscores or dots, no version numbers in the ID.

Prices always come from the store

Never display a hard-coded price. Currency, tax-inclusive display and regional pricing are the store's job, and showing the wrong one is a policy violation in several markets.

Fallback rule when the store has not answered yet: show the local list price only for the currency you actually know (e.g. your home market), and show no price at all for everyone else — a wrong currency is worse than a bare "Buy" button.

Offline and refunds

Four states, and code must handle all four:

The third row is the bug nobody writes a test for. Write the test.

Platform notes

• Android — references/android-play-billing.md. Play Billing Library 8+ is mandatory for new uploads and updates since 31 Aug 2026; latest is 9.1.0. v8 renamed "in-app items" to "one-time products" and removed querySkuDetailsAsync, queryPurchaseHistory and the no-arg enablePendingPurchases.
• iOS — references/ios-storekit.md. StoreKit 2 (Product, Transaction, Transaction.updates) is the default; it verifies signatures for you. You must run a Transaction.updates listener for the whole app lifetime or you will drop purchases made outside your flow.
• Server validation — references/server-receipt-validation.md. Required the moment a purchase grants something a cheater would want. Play: Developer API + Real-time developer notifications (RTDN). Apple: App Store Server API + Server Notifications V2.

Policy rules that cause rejection

• Digital content must use the platform's IAP. Both stores. Taking Stripe/PayPal/bank transfer for in-game content gets the app removed. (Physical goods and real-world services are the exception, and must not use IAP.)
• US App Store only, since May 2025: apps may include buttons and links to external purchase pages with no entitlement required. Outside the US storefront the old restriction still applies. Do not build a link-out flow globally on the strength of a US headline.
• A restore path is mandatory on iOS for non-consumables. A visible "Restore purchases" button. Rejections under 3.1.1 for a missing one are routine.
• Kids' apps: purchase entry points must sit behind a parent gate, and the gate must not be solvable by a young child (no simple "tap the biggest number"). See app-auth and store-listing for the Families/Kids declarations that follow from selling to children.
• Do not promise content you gate later. Changing a bought unlock into a subscription is a refund event and a review-bomb event.

Testing

Ranked by what actually catches bugs:

1. FakeStoreBackend unit tests — every row of the offline/refund table above, plus double-purchase, purchase-while-owned, and cancelled flows. These run in CI with no store.
2. Android closed testing / license testers — real Play dialogs, no charge. License testers are set at the account level in Play Console, not per build. Purchases still have to be refunded/consumed between runs for consumables.
3. iOS sandbox / StoreKit configuration file — the .storekit file lets you test in the simulator without App Store Connect at all; do both, because the file does not catch App Store Connect misconfiguration.

Checklist before you call IAP done: references/pre-launch-checklist.md

Sources

Specs verified 2026-09-24:

• Play Billing release notes
• StoreKit
• App Review Guidelines 3.1