IAP Catalog Specification

Agent Prompt Snippet

Ensure the project has an IAP catalog specification covering purchasable items, currency bundles, pricing tiers, and store integration.

Purpose

An IAP Catalog Specification is the single source of truth for every item, bundle, and virtual currency a player can purchase inside your game. It defines every SKU with its platform-specific product identifier, human-readable name, description, icon asset reference, price tier on each storefront (Apple App Store, Google Play, Steam, PlayStation Store, Microsoft Store, Nintendo eShop), virtual currency exchange rate, and any bundle or promotional grouping it belongs to. It is the document that maps the game’s monetization design into the concrete data structures that platform store APIs, server-side entitlement services, and client UI all consume.

Without an IAP catalog spec, the gap between “the game has purchasable items” and “the game correctly charges, delivers, validates, and reports on purchasable items across six storefronts” is filled with ad-hoc decisions. A designer adds a skin pack and picks a price; an engineer hardcodes the Apple product ID but forgets Google’s; finance discovers the revenue share math is wrong three weeks after launch. The catalog spec eliminates this by requiring that every purchasable entity be fully defined—price, platform mapping, receipt validation flow, refund behavior, and legal disclosure—before it enters development.

The spec also addresses regulatory requirements that vary by jurisdiction: loot box probability disclosures (required in China, Belgium, and increasingly elsewhere), age-gating for certain purchase types, and GDPR-related consent for purchase history tracking. A catalog spec that omits probability tables for randomized items is incomplete regardless of how well it documents deterministic SKUs.

This is a Required document for any game with in-app purchases. Without it, the team will ship inconsistent pricing, fail platform certification, and discover legal compliance gaps through app store rejections or regulatory action.

Who needs this document

Persona	Why they need it	How they use it
Sam (Indie Dev)	Selling IAPs across even two platforms means managing two sets of product IDs, two price tier systems, two receipt validation APIs, and two revenue share models; the catalog spec keeps them aligned	Writes the catalog during pre-production alongside the monetization model; references it when configuring products in App Store Connect and Google Play Console
Claude Code (AI Agent)	Cannot generate correct store integration code without knowing exact product IDs, price tier mappings, consumable vs. non-consumable classification, and receipt validation endpoints	Reads the catalog spec before implementing any purchase flow; validates that SKU identifiers in code match the documented catalog; ensures entitlement delivery handles every item type
Priya (Eng Lead)	Coordinates client, server, and analytics teams around a shared item taxonomy; prevents integration failures where the client requests a product ID the server doesn’t recognize	Reviews the catalog spec during sprint planning; uses it to validate that server entitlement tables, client store wrappers, and analytics event schemas reference the same canonical item definitions
DevOps (Infrastructure)	Configures server-side receipt validation services, manages store API credentials, and monitors purchase success rates	Uses the catalog spec to provision receipt validation endpoints per platform, configure webhook receivers for subscription events, and set alerting when purchase failure rates exceed thresholds

What separates a good version from a bad one

Criterion 1: Every SKU has a complete platform mapping with price tiers

✓ Strong: “SKU gem_pack_500: Type: consumable. Apple product ID: com.studio.game.gems500, Price Tier 3 ($2.99 USD). Google product ID: gems_500, default price $2.99 USD with auto-converted local pricing enabled. Steam item ID: 1001, price $2.99 USD / €2.79 EUR / £2.49 GBP. Virtual currency grant: 500 gems. Revenue share: Apple 30% (15% under Small Business Program if qualified), Google 15% first $1M then 30%, Steam 30% declining at $10M/$50M thresholds.”

✗ Weak: “Gem pack: 500 gems for $2.99.” (Which platforms? What are the product IDs? What about localized pricing? What’s the revenue share impact on margin? A single line like this generates a dozen questions before anyone can implement it.)

Criterion 2: Consumable, non-consumable, and subscription types are classified with entitlement rules

✓ Strong: “Item types: (1) Consumable — gems, coins, energy refills; granted on purchase, decremented on use, re-purchasable. Server validates receipt, credits balance atomically, stores transaction ID for deduplication. (2) Non-consumable — character skins, map packs; granted permanently, purchase restored on reinstall via platform restore API. Server maintains entitlement record keyed by player ID + SKU. (3) Subscription — Battle Pass ($9.99/month); Apple/Google manage renewal; server receives webhook on renewal/cancellation/grace period, updates entitlement flag within 5 minutes.”

✗ Weak: “Players can buy gems and skins.” (No classification of item types. Engineers don’t know whether skins should be restorable. The server team doesn’t know whether gem purchases need deduplication. Subscriptions aren’t mentioned at all.)

Criterion 3: Receipt validation flow is specified per platform

✓ Strong: “Receipt validation: Client sends platform receipt to POST /api/v1/purchases/validate. Server validates against Apple (verifyReceipt endpoint, shared secret in AWS Secrets Manager, retry on 21002 with production URL fallback) and Google (Play Developer API v3, service account credential, purchases.products.get for one-time, purchases.subscriptions.get for subs). Validation is synchronous — client blocks until server confirms. On failure: client shows ‘Purchase could not be verified’ and does not grant entitlement. All receipts logged with platform, SKU, transaction ID, result, and timestamp.”

✗ Weak: “Receipts are validated server-side.” (Which API? What credentials? What happens on failure? What’s the retry strategy? What’s logged? This sentence provides zero implementation guidance.)

Criterion 4: Loot box and randomized item probabilities are disclosed

✓ Strong: “Randomized items: Premium Chest (SKU premium_chest_1) contains one item drawn from: Legendary (5.0%), Epic (15.0%), Rare (30.0%), Common (50.0%). Probabilities displayed in-game on the chest purchase screen and item description tooltip. Pity system: guaranteed Legendary within 20 consecutive chests (counter resets on drop). Probabilities stored server-side in loot_tables config; client fetches rates at session start. China App Store submission includes separate probability disclosure per SAPPRFT regulation.”

✗ Weak: “Chests contain random items of varying rarity.” (No probabilities. This fails Apple App Store Review Guideline 3.1.1, Google Play policy section on randomized items, and Chinese regulatory requirements. The app will be rejected.)

Common mistakes

Hardcoding prices instead of using platform price tiers. Apple and Google define price tier tables with localized pricing for every supported currency. Teams that hardcode “$2.99” instead of referencing “Tier 3” discover at launch that their game costs ¥2.99 in Japan or that currency conversions produce prices ending in .37. The catalog spec must map each SKU to the platform’s native tier system and document how localized prices are reviewed.

Forgetting the refund path. Apple and Google both allow customer-initiated refunds and notify the developer via server notification. A catalog spec that only covers the purchase flow and ignores refund handling leaves the server granting permanent entitlements for refunded purchases. Each item type needs a documented refund policy: consumable already spent → flag account for review; non-consumable → revoke entitlement; subscription → downgrade at period end.

Treating all platforms as identical. Steam’s IAP model uses a fundamentally different flow (MicroTxn API callback) than mobile stores. Console stores have their own certification requirements, entitlement APIs, and revenue share terms. A catalog spec that documents only one platform’s flow and says “other platforms are similar” guarantees integration bugs on every other platform.

No versioning scheme for the catalog itself. Live games add, remove, and reprice items continuously. Without a version number and changelog, the server can be running catalog v12 while the client shipped with v10, producing phantom items or missing entries. The spec should define how catalog versions are distributed and how deprecated SKUs are sunset.

Omitting bundle decomposition rules. Bundles containing both consumables and non-consumables need clear rules: if a player already owns the non-consumable skin in a “Starter Bundle,” does the price change? Is the skin replaced with currency? Apple and Google have different policies, and the catalog spec must document the resolution per platform.

How to use this document

When to create it

Write the IAP catalog spec after the monetization model establishes what the game sells and why, but before configuring any products in platform store dashboards. The spec should be finalized before the first closed beta that includes real purchases, because platform product IDs are difficult to change after creation. Budget a review pass when adding new platforms or targeting regions with distinct regulatory requirements.

Who owns it

The product manager or monetization designer owns the catalog spec. Engineering (client store integration and server entitlement leads), QA, legal (probability disclosure and refund compliance), and finance (revenue share and reporting) are reviewers. Changes to pricing tiers, new item types, or new platform additions require sign-off from all reviewers because they cascade into store configuration, entitlement logic, analytics, and financial reporting.

How AI agents should reference it

get_standard_docs(type="video_game", features=["monetization"])
→ iap_catalog_spec in documents[]
→ agent reads spec before generating any store integration or purchase flow code
→ agent validates that product IDs in code match documented SKUs exactly
→ agent checks that all item types (consumable, non-consumable, subscription) have corresponding entitlement logic
→ agent verifies that randomized items include probability disclosure in UI code

The prompt_snippet — “Ensure the project has an IAP catalog specification covering purchasable items, currency bundles, pricing tiers, and store integration” — tells the agent to verify these four dimensions exist and are concrete, not aspirational.

How it connects to other documents

The IAP Catalog Specification is downstream of the Monetization Model (which defines what the game sells and the strategic rationale), and upstream of the API Reference (which documents the server endpoints that validate receipts and grant entitlements), the Platform Certification Checklist (which tracks store-specific submission requirements that the catalog must satisfy), and the GDPR Compliance Checklist (which governs how purchase history and player spending data are collected, stored, and deletable on request).