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

Obtain

StoreController

via

UnityIAPServices.StoreController()

(or individual services via

DefaultStore()

DefaultProduct()

DefaultPurchase()

)

Subscribe to all required events (see Required Event Subscriptions below) before calling
```
Connect()
```
```
await store.Connect()
```
to connect to the platform store

OnStoreConnected

, call

store.FetchProducts(List<ProductDefinition>)

to load the catalog

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.

```
store.PurchaseProduct(product)
```
— initiates the platform purchase dialog
```
OnPurchasePending
```
fires — you receive a
```
PendingOrder
```
Validate the receipt, grant content to the player
```
store.ConfirmPurchase(pendingOrder)
```
— finalizes the transaction
```
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 re-fetched — confirmed consumables are not returned (see Two-Step Purchase Flow above).

Subscription Info

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.

Required Event Subscriptions

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.

Failure Description Property Names

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`	—

Validation

After writing code that uses this package:

Verify the project compiles without errors.
Confirm all API calls match the v5 signatures in api-notes.md — do NOT use v4 legacy patterns (
```
IStoreListener
```
,
```
UnityPurchasing.Initialize
```
,
```
ConfigurationBuilder
```
).
Check the "Anti-Hallucination: Common v5 Mistakes" table in api-notes.md — do NOT use
```
OnStoreConnectionFailed
```
(use
```
OnStoreDisconnected
```
), do NOT pass callbacks to
```
FetchProducts
```
/
```
FetchPurchases
```
(use events), do NOT use
```
product.receipt
```
(use
```
order.Info.Receipt
```
).
Check that all required events are subscribed before calling
```
Connect()
```
(see Required Event Subscriptions table above).
Verify the two-step purchase flow:
```
OnPurchasePending
```
→ grant content →
```
ConfirmPurchase(pendingOrder)
```
.
Confirm both success and failure events are subscribed for every async operation (
```
OnProductsFetched
```
/
```
OnProductsFetchFailed
```
,
```
OnStoreConnected
```
/
```
OnStoreDisconnected
```
, etc.).
If handling subscriptions, verify
```
IsSubscribed()
```
is compared with
```
== Result.True
```
, not cast to
```
bool
```
.
If updated files coexist with legacy versions in the same project, use a unique namespace (e.g., add
```
.Updated
```
suffix) to avoid CS0101/CS0111 compilation errors.
If the project subscribes to
```
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.

implement-in-app-purchases

NPX Install

Tags

SKILL.md Content