Purchases
Retrieve purchase information and determine purchase status for products bought by players.
Read time 1 minuteLast updated 7 months ago
Unity IAP fetches purchase information from the store so your application can recognize and fulfill what players have bought. This ensures that your game can deliver content or entitlements to users based on their purchase history, even if they bought items outside your app or on another device.
A purchase is represented as an object. The contains all relevant details about the purchase and provides information needed to track and manage it with the store.
OrderOrderRetrieve purchases
Purchases made by the user can be retrieved from the store. However, consumable products must be tracked by your application after they are consumed, because stores don't return consumables that have already been fulfilled. For non-consumable products and subscriptions, the store accurately returns these purchases when you call or .
FetchPurchasesCheckEntitlementDetermine purchase status
You can determine the status of a purchase in two ways:
- Use to determine if the
Orderis aOrder,PendingOrder,ConfirmedOrderorDeferredOrder.FailedOrder - Use to receive
CheckEntitlement, which returnsEntitlementStatus,EntitledButNotFinished,EntitledUntilConsumed,FullyEntitledorNotEntitled.Unknown
Purchase attributes
Attribute | Description |
|---|---|
| A unique identifier for the purchase. |
| The purchased product. |
| The quantity of the product purchased. |
| Receipt data for validating the purchase with the store. |
Purchase states
State | Description |
|---|---|
| The purchase has been paid but not yet fulfilled. |
| The purchase has been fulfilled and acknowledged. |
| The purchase failed due to an error. |
| The purchase is waiting for payment. |
Process purchases
The callback is invoked when a purchase is made and is awaiting fulfillment. Your application should fulfill the purchase at this point, for example by unlocking local content or sending the purchase receipt to a server to update a server-side game model.
OnPurchasePendingNote that may be called at any point following a successful initialization. If your application crashes during execution of the handler, then it is invoked again the next time Unity IAP initializes. Consider implementing your own de-duplication logic.
OnPurchasePendingOnPurchasePendingNote
If you don't confirm purchases, the store sends back the purchases, and some stores may even refund it automatically to protect the users.
// Handle restore on initializationprivate async void Start(){ // Setup, e.g. add listeners to your StoreController... m_StoreController.OnPurchasePending += OnPurchasePending; m_StoreController.OnPurchasesFetched += OnPurchasesFetched; m_StoreController.OnPurchaseConfirmed += OnPurchaseConfirmed; await m_StoreController.Connect(); // Fetch previous purchases (includes confirmed orders) m_StoreController.FetchPurchases();}// Handle new purchases and pending transactionsprivate void OnPurchasePending(PendingOrder order){ ProcessPurchase(order);}// Handle fetched purchases (includes previously confirmed orders)private void OnPurchasesFetched(Orders orders){ foreach (var confirmedOrder in orders.ConfirmedOrders) { if (confirmedOrder.CartOrdered.Items().FirstOrDefault()?.Product.definition.type != ProductType.Consumable) { // Mark non-consumable and subscription products as entitled on fetch, as they only need to be granted once MarkAsEntitled(confirmedOrder.CartOrdered.Items().FirstOrDefault().Product); } }}// Your ProcessPurchase logicprivate void ProcessPurchase(PendingOrder order){ foreach (var product in order.CartOrdered.Items()) { // Grant product GrantProduct(product); } // Confirm the order to finalize the transaction m_StoreController.ConfirmPurchase(order);}
Handle a failed confirmation
A call to can fail. The event reports both outcomes, so it delivers an rather than a . Check the type of the order before you treat the purchase as complete.
ConfirmPurchaseOnPurchaseConfirmedOrderConfirmedOrderA confirmation fails in the following cases. Refer to the following table for information on which failures are worth retrying.
Cause | Failure reason | Recovery |
|---|---|---|
The order you pass is | | Don't retry. Pass the |
| The order has no order information, or no transaction ID. | | Don't retry. The order can't be confirmed in this state. |
| The store isn't connected, for example, because the device lost its network connection. | | Retry the confirmation after the store reconnects. |
| The store already finished the transaction. IAP reports this for Apple platforms as of version 5.4.2. | | Don't retry. Treat the purchase as complete. |
| An unexpected error occurs during confirmation. | | Retry the confirmation. |
To retry a confirmation, keep the that you passed to . delivers a instead of the original , so you can't pass the failed order back to . An order that stays pending is also redelivered through the next time Unity IAP initializes.
PendingOrderConfirmPurchaseOnPurchaseConfirmedFailedOrderPendingOrderConfirmPurchaseOnPurchasePendingThe following example handles both types of order:
private void OnPurchaseConfirmed(Order order){ switch (order) { case ConfirmedOrder confirmedOrder: // The store acknowledged the purchase SetOwnedState(confirmedOrder); break; case FailedOrder failedOrder: // The store didn't acknowledge the purchase Debug.LogError($"Confirmation failed: {failedOrder.FailureReason} - {failedOrder.Details}"); break; }}
Note
A failed confirmation doesn't reverse the purchase or revoke the reward that you granted. Unity IAP keeps the order pending until a confirmation succeeds, so don't grant the reward again.
Reflect purchase state in your UI
Keep your buy buttons in sync with the purchase and entitlement state that Unity IAP reports, rather than treating them as always available. Syncing button states prevents duplicate purchase attempts, avoids offering a product the player already owns, and gives clear feedback while a purchase is processing. The correct mapping depends on the product type.
Non-consumables and subscriptions
Non-consumable and subscription products are entitled once and shouldn't be offered for purchase while the user owns them.
After succeeds, or when returns , reflect that entitlement state in your UI instead of a purchase action:
FetchPurchasesCheckEntitlementFullyEntitled- Non-consumables: Show an Owned state. Non-consumables are purchased once and owned forever, so no further action is needed unless the purchase is later refunded.
- Subscriptions: Show a Manage or Renew action. Unlike non-consumables, subscriptions can expire or be canceled, so provide a mechanism for the player to manage, renew, or cancel them.
Because subscriptions can expire, reevaluate subscription state on each app launch. Don't permanently cache subscriptions as owned.
Consumables
Consumables are normally available for purchase. Don't deactivate the buy button based on entitlement.
NotEntitledOnly deactivate the buy button when there's an unfinished order. If a consumable has an associated , either reported through or returned as by , complete the order before reenabling the button:
PendingOrderOnPurchasePendingEntitledUntilConsumedCheckEntitlement- Grant the reward.
- Call .
ConfirmPurchase - Re-enable the buy button.
Don't permanently deactivate the buy button of a consumable after purchase.
Update the button state during purchase flow
Deactivate the buy button when the purchase starts, whether you call or the Direct-to-Consumer (D2C) .
PurchaseProductShowPurchaseOptionBecause the button is deactivated when the purchase starts, update its state in every callback that can resolve the purchase attempt. Otherwise, the button can remain deactivated.
Update the button state in the following callbacks when the purchase attempt resolves:
Callback | Description |
|---|---|
| The purchase is paid and awaiting fulfillment. This order can be a new purchase or an unconfirmed order redelivered at launch. After you fulfill and confirm the order, set the resolved state: owned for a non-consumable product or subscription, or buyable for a consumable product. For more information, refer to Process purchases. |
| The confirmation attempt resolved. This event delivers an |
| The purchase failed or the player canceled it. Return the button to its buyable state. |
| The purchase is deferred and waiting to complete, such as for Ask to Buy approval. Show a waiting state instead of re-enabling the button. |
| Purchases retrieved on launch or restore. Set the owned state for any non-consumable products and subscriptions the player already owns. |
| The fetch couldn't complete, including when the device is offline and the status is |
Register , , and on your during setup, as shown in the example in Process purchases. Register the remaining callbacks in the table the same way.
OnPurchasePendingOnPurchaseConfirmedOnPurchasesFetchedStoreControllerNote
You don't need to call to keep the UI in sync. The purchase and entitlement state is available from the objects that returns and from pending orders delivered through .
CheckEntitlementOrderFetchPurchasesOnPurchasePendingCheckEntitlementPurchase acknowledgement and reliability
Unity IAP requires you to explicitly acknowledge purchases to ensure that purchases are reliably fulfilled, even during network outages or application crashes. If a purchase is paid for but not fulfilled, Unity IAP delivers the purchase to your application the next time it initializes. This process prevents purchases from being lost when the purchase flow is interrupted or when purchases are completed while the application is offline.
After successfully fulfilling a purchase, call with the relevant to acknowledge the purchase to the store.
ConfirmPurchasePendingOrderWarning
Always acknowledge purchases. If you don't, the following can happen:
- Unity IAP re-invokes for the order on every subsequent
OnPurchasePendingcall or session start until you acknowledge it. Without your own de-duplication logic, this can grant the same item more than once.FetchPurchases - Some stores reverse the purchase automatically. For example, Google Play refunds an unacknowledged purchase after three days, and the Apple App Store applies similar protective logic on a less strict timeline.
- To the player, the purchase appears to succeed and then disappear, which looks like a broken purchase.
Note
For consumables, once you acknowledge the purchase, the store does not return it again. Always persist consumable rewards remotely. If you store consumable rewards locally, you risk losing data with no way to restore it.
Acknowledge purchases persisted to the cloud
If you are saving consumable purchases to the cloud, you must call when you have successfully persisted the purchase.
ConfirmPurchaseWhen returning , Unity IAP keeps transactions open on the underlying store until confirmed as processed. This ensures consumable purchases are not lost even if a user reinstalls your application while a consumable is pending.
Pending