unity-technologies/implement-in-app-purchases

Unity In-App Purchasing

Namespace: UnityEngine.Purchasing | Security: UnityEngine.Purchasing.Security Package: com.unity.purchasing

Unity IAP has its own initialization path via UnityIAPServices.StoreController() → store.Connect(). It does not require UnityServices.InitializeAsync(), but they can coexist if your project uses other UGS services. If Analytics is present and InitializeAsync() is called, IAP will automatically send transaction events.

Before You Start

Always read references/pre-check.md first. It scans the project for third-party IAP packages, native Google Billing, and existing Unity IAP versions, then routes to the correct path. Do not read any other reference file or make any changes until routing is resolved.

Detailed References

• Project scan and path routing (read first): See references/pre-check.md
• API signatures & code examples: See references/api-notes.md
• Platform extensions (Apple, Google): See references/platform-notes.md
• Editing IAPProductCatalog.json (schema, decimal serialization, refresh): See references/codeless-catalog.md
• v4 → v5 migration: See references/migration-v4-to-v5.md
• Convert native Google BillingClient to Unity IAP 5: See references/path-convert-native-google-billing.md
• Convert native iOS StoreKit plugin to Unity IAP 5: See references/path-convert-native-storekit.md
• Convert Essential Kit billing to Unity IAP 5: See references/convert-essentialkit.md
• UniPay (FLOBUK) — assessment and guidance: See references/convert-unipay.md
• RevenueCat — conversion assessment and guidance: See references/convert-revenuecat.md
• Adapty — conversion assessment and guidance: See references/convert-adapty.md
• Add Unity IAP 5 to a project with no existing IAP: See references/path-add-iap-to-new-project.md
• Implement IAP D2C Capabilities (third-party payment provider — Stripe/Coda, requires v5.4+): See references/path-implement-iap-d2c.md

Read reference files on demand — only when you need specific API signatures, platform extension details, or migration mappings.

Initialization Flow

1. Obtain StoreController via UnityIAPServices.StoreController() (or individual services via DefaultStore(), DefaultProduct(), DefaultPurchase())
2. Subscribe to all required events (see Required Event Subscriptions below) before calling Connect()
3. await store.Connect() to connect to the platform store
4. On OnStoreConnected, call store.FetchProducts(List<ProductDefinition>) to load the catalog
5. On OnProductsFetched, products are ready for display and purchase

Use Awake() for initialization — ensures IAP is ready before other Start() methods.

Product types: ProductType.Consumable, ProductType.NonConsumable, ProductType.Subscription.

Fetching Products

Define products as List<ProductDefinition> and pass to store.FetchProducts(). Use StoreSpecificIds when product IDs differ across Apple/Google stores. For complex catalogs, use CatalogProvider to manage product sets and store-specific IDs.

Method	Behavior
GetProducts()	Returns the cached product list (synchronous, stale if FetchProducts not called)
FetchProducts()	Queries the store for fresh pricing/availability and updates the cache
GetProductById(id)	Returns a single cached product by ID

These are NOT interchangeable. Always call FetchProducts() first before relying on GetProducts().

Two-Step Purchase Flow

IAP v5 uses a mandatory two-step flow: Pending → Confirm.

1. store.PurchaseProduct(product) — initiates the platform purchase dialog
2. OnPurchasePending fires — you receive a PendingOrder
3. Validate the receipt, grant content to the player
4. store.ConfirmPurchase(pendingOrder) — finalizes the transaction
5. OnPurchaseConfirmed fires — receives Order base type; pattern-match ConfirmedOrder (success) vs FailedOrder (confirmation failed)

You MUST call ConfirmPurchase(pendingOrder) after granting content. Unconfirmed purchases are re-delivered on next app launch to prevent lost purchases.

De-duplication: OnPurchasePending may fire multiple times for the same purchase (e.g., app restart before confirmation). Always check if content was already granted.

Consumables: Confirmed consumable purchases are NOT returned by FetchPurchases. Track consumable grants yourself (e.g., in Cloud Save or Economy).

Deferred purchases: OnPurchaseDeferred fires for Ask-to-Buy (iOS) and Google Play deferred purchases. Do NOT grant content — wait for OnPurchasePending when approved.

Restore Transactions

store.RestoreTransactions(callback) re-delivers non-consumable and subscription purchases. Each restored purchase triggers OnPurchasePending.

Required on iOS for Apple App Store compliance — add a "Restore Purchases" button.

Apple non-renewable subscriptions cannot be restored via RestoreTransactions. Track these server-side.

Receipt Validation

Platform	Approach
Google Play	CrossPlatformValidator with GooglePlayTangle.Data() — local validation supported
Apple (StoreKit 2)	Local validation is a no-op. Use order.Info.Apple?.jwsRepresentation for server-side validation

Generate tangle data via Services > In-App Purchasing > Receipt Validation Obfuscator in the Unity Editor.

Entitlement Checking

Use when you don't have the Order and want to know the status of a specific product (replaces v4's product.hasReceipt). If you already have the Order, check its type instead: PendingOrder maps to EntitledUntilConsumed (consumables) or EntitledButNotFinished (non-consumables/subscriptions), ConfirmedOrder maps to FullyEntitled.

Call store.CheckEntitlement(product) and handle store.OnCheckEntitlement. Check entitlement.Status == EntitlementStatus.FullyEntitled.

EntitlementStatus values: FullyEntitled, EntitledUntilConsumed, EntitledButNotFinished, NotEntitled, Unknown.

Fetch Existing Purchases

store.FetchPurchases() retrieves all current purchases from the store. Useful at app startup.

Method	Behavior
GetPurchases()	Returns the cached purchase list
FetchPurchases()	Queries the store for current purchases and overwrites the cached list

FetchPurchases() replaces the entire cached list on each call. Only non-consumables and subscriptions are r