Unity IAP 5: What Changed from IAP 4 and How to Migrate

Unity In-App Purchasing (IAP) version 5 replaces the interface-based architecture of IAP 4 with a single event-driven StoreController class. Migrating requires code changes: the IStoreListener and IDetailedStoreListener interfaces and the ConfigurationBuilder are removed, initialization is asynchronous, and purchases are processed through lifecycle events. IAP 5 also enables web-to-mobile monetization, custom payment processors (such as Stripe and Coda), and standalone webshops.

What you need to know about Unity IAP 5

• Unity IAP 5 removes the IStoreListener and IDetailedStoreListener interfaces required in IAP 4.
• All purchase logic in Unity IAP 5 runs through one class: UnityIAPServices.StoreController(), which fires events across the purchase lifecycle.
• The ConfigurationBuilder from IAP 4 is removed. Product definitions are passed directly to FetchProducts() as ProductDefinition objects with an ID and a product type.
• The legacy IDs class is renamed StoreSpecificIds in IAP 5.
• Unity IAP 5 initialization is asynchronous and requires Unity Gaming Services to be initialized first via await UnityServices.InitializeAsync().
• Apple receipts in IAP 5 are validated automatically through StoreKit 2 before reaching the developer. Google Play validation requires the developer's Google license key, obfuscated with the tool included in the IAP package.
• StoreKit 1 support returns in IAP 5 for devices that cannot upgrade to iOS 15.0 (devices older than iPhone 6s).
• A working reference implementation ships in the package: the Minimal Coded IAP Sample (PaywallManager script), available in the Unity Package Manager.

How to migrate from Unity IAP 4 to IAP 5

Migration follows four steps:

Initialize and connect. Initialize Unity Gaming Services, obtain a StoreController, subscribe to its events, and call Connect() to reach Google Play or the Apple App Store. Use OnStoreConnected and OnStoreDisconnected to toggle purchase UI.

Fetch products. Build a List<ProductDefinition> from the Editor's IAP product catalog or in code (for example, new ProductDefinition("gem_chest_01", ProductType.Consumable)) and pass it to FetchProducts(). The store returns localized prices and descriptions.

Fetch pending purchases. Call FetchPurchases() to recover interrupted or postponed transactions. Pending orders arrive through the OnPurchasePending event, but developers should also process orders.PendingOrders, because pending events can be missed on some iOS versions. Confirmed non-consumables and subscriptions can be re-entitled at this point.

Purchase, grant, confirm. Call PurchaseProduct(product). In OnPurchasePending, grant the item, validate the receipt, and call ConfirmPurchase(pendingOrder). Handle failures in OnPurchaseFailed — a user cancellation needs no message, other errors should be surfaced to the player.

The Unity IAP 5 purchase flow

Use the infographic below to view the entire purchase flow for Unity IAP5, including the new features, webshops, catalogs, and payment providers.

Download the high-resolution PDF here.

Common pitfalls when upgrading to IAP 5

• Duplicate grants: the same order can surface through both OnPurchasePending and a manual pending-order pass. Track processed transactions in a HashSet (populated from OnPurchasesConfirmed) and check it before granting.
• Concurrent purchases: disable purchase buttons while an order is in flight to prevent duplicate requests.
• Event leaks: IAP 5 is event-driven — unsubscribe from all StoreController events when the purchasing manager is destroyed.
• StoreKit 1 suspended purchases: on pre-iOS 15 devices, unconfirmed purchases can block a player from repurchasing the same product. A backend that tracks and resolves these purchases is recommended.

Server-side verification

Transaction IDs from IAP 5 orders can be sent to Unity Cloud Code for server-side verification, with items granted to players through Unity Economy.

Learn more about Unity IAP5 integration →