Terminal
Terminal/Skill
Adds, configures and debugs real money purchases in Unity, including subscriptions, receipt validation and direct payments through Stripe or Coda.
By Unity
Works with
npx skills add unity-technologies/skills --skill implement-in-app-purchasesNamespace: 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.
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.
IAPProductCatalog.json (schema, decimal serialization, refresh): See references/codeless-catalog.mdRead reference files on demand — only when you need specific API signatures, platform extension details, or migration mappings.
StoreController via UnityIAPServices.StoreController() (or individual services via DefaultStore(), DefaultProduct(), DefaultPurchase())Connect()await store.Connect() to connect to the platform storeOnStoreConnected, call store.FetchProducts(List<ProductDefinition>) to load the catalogOnProductsFetched, products are ready for display and purchaseUse Awake() for initialization — ensures IAP is ready before other Start() methods.
Product types: ProductType.Consumable, ProductType.NonConsumable, ProductType.Subscription.
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().
IAP v5 uses a mandatory two-step flow: Pending → Confirm.
store.PurchaseProduct(product) — initiates the platform purchase dialogOnPurchasePending fires — you receive a PendingOrderstore.ConfirmPurchase(pendingOrder) — finalizes the transactionOnPurchaseConfirmed 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.
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.
| 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.
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.
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 re-fetched — confirmed consumables are not returned (see Two-Step Purchase Flow above).
Subscription info is on IPurchasedProductInfo, accessed via order.Info.PurchasedProductInfo — NOT on CartItem (CartItem only has Product and Quantity).
IsSubscribed() returns Result enum (True/False/Unsupported), NOT bool. Use == Result.True for null-safe comparison.
Always subscribe to BOTH success and failure events. Not subscribing to failure events generates runtime warnings.
| Call | Success Event | Failure Event (REQUIRED) |
|---|---|---|
FetchProducts() | OnProductsFetched | OnProductsFetchFailed |
FetchPurchases() | OnPurchasesFetched | OnPurchasesFetchFailed |
Connect() | OnStoreConnected | OnStoreDisconnected |
PurchaseProduct() | OnPurchasePending | OnPurchaseFailed |
CheckEntitlement() | OnCheckEntitlement | — |
Always subscribe to OnPurchaseDeferred — fires for Ask-to-Buy (iOS) and Google Play deferred purchases. Not subscribing silently drops deferred purchases.
Subscribe to events BEFORE calling Connect() — pending purchases from a previous session may fire immediately.
These property names are NOT interchangeable — using the wrong one causes CS1061:
| Type | Field | Property | NOT |
|---|---|---|---|
StoreConnectionFailureDescription | .message | .Message | .reason |
ProductFetchFailed | — | .FailureReason, .FailedFetchProducts | .Message |
FailedOrder | — | .FailureReason, .Details | — |
PurchasesFetchFailureDescription | .message, .failureReason | .Message, .FailureReason | — |
After writing code that uses this package:
IStoreListener, UnityPurchasing.Initialize, ConfigurationBuilder).OnStoreConnectionFailed (use OnStoreDisconnected), do NOT pass callbacks to FetchProducts/FetchPurchases (use events), do NOT use product.receipt (use order.Info.Receipt).Connect() (see Required Event Subscriptions table above).OnPurchasePending → grant content → ConfirmPurchase(pendingOrder).OnProductsFetched/OnProductsFetchFailed, OnStoreConnected/OnStoreDisconnected, etc.).IsSubscribed() is compared with == Result.True, not cast to bool..Updated suffix) to avoid CS0101/CS0111 compilation errors.OnAuthAccountChanged (v5.4+): verify the handler re-fetches products and purchases from scratch — Unity IAP clears both caches before raising this event. Do not read GetProducts() or GetPurchases() inside the handler.