Fulfill purchases through the SDK

Retrieve purchase information and determine purchase status for products bought by players.

Read time 2 minutes

Last updated a month ago

Important

For Payment Providers, you must specify the store name (

PaymentProvider.Name

) when you call the

UnityIAPServices

StoreController

PaymentProvider.Name

specifies that you want to use a Direct-to-Consumer (D2C) provider integration and does not return the display name of the provider.

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

Order

object. The

Order

contains all relevant details about the purchase and provides information needed to track and manage it with the store.

Retrieve 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

FetchPurchases

CheckEntitlement

Determine purchase status

You can determine the status of a purchase in two ways:

Use

Order

to determine if the

Order

is a

PendingOrder

ConfirmedOrder

DeferredOrder

FailedOrder

Use

CheckEntitlement

to receive

EntitlementStatus

, which returns

EntitledButNotFinished

EntitledUntilConsumed

FullyEntitled

NotEntitled

Unknown

Purchase attributes

Attribute	Description
`transactionId`	A unique identifier for the purchase.
`product`	The purchased product.
`quantity`	The quantity of the product purchased.
`receipt`	Receipt data for validating the purchase with the store.

Purchase states

State	Description
`Pending`	The purchase has been paid but not yet fulfilled.
`Confirmed`	The purchase has been fulfilled and acknowledged.
`Failed`	The purchase failed due to an error.
`Deferred`	The purchase is waiting for payment.

Process purchases

The

OnPurchasePending

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.

Note that

OnPurchasePending

may be called at any point following a successful initialization. If your application crashes during execution of the

OnPurchasePending

handler, then it is invoked again the next time Unity IAP initializes. Consider implementing your own de-duplication logic.

Note

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;    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);}

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

FetchPurchases

succeeds, or when

CheckEntitlement

returns

FullyEntitled

, reflect that entitlement state in your UI instead of a purchase action:

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.

NotEntitled

is expected for a consumable that the player can buy again.

Only deactivate the buy button when there's an unfinished order. If a consumable has an associated

PendingOrder

, either reported through

OnPurchasePending

or returned as

EntitledUntilConsumed

CheckEntitlement

, complete the order before reenabling the button:

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

PurchaseProduct

or the Direct-to-Consumer (D2C)

ShowPurchaseOption

Because 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
`OnPurchasePending`	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.
`OnPurchaseConfirmed`	The order has been fulfilled and acknowledged. Use this callback to set the final owned state for non-consumable products and subscriptions if you don't do so in `OnPurchasePending` .
`OnPurchaseFailed`	The purchase failed or the player canceled it. Return the button to its buyable state.
`OnPurchaseDeferred`	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.
`OnPurchasesFetched`	Purchases retrieved on launch or restore. Set the owned state for any non-consumable products and subscriptions the player already owns.
`OnPurchasesFetchFailed`	The fetch couldn't complete, including when the device is offline and the status is `Unknown` . Leave the button in its buyable state so the player isn't locked out of a purchase they're entitled to make.

StoreController

during setup, as shown in the example in Process purchases.

Note

You don't need to call

CheckEntitlement

to keep the UI in sync. The purchase and entitlement state is available from the

Order

objects that

FetchPurchases

returns and from pending orders delivered through

OnPurchasePending

CheckEntitlement

is an optional convenience method that returns the status of a single product, so you don't have to inspect fetched orders yourself.

Purchase 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

ConfirmPurchase

with the relevant

PendingOrder

to acknowledge the purchase to the store.

Warning

Always acknowledge purchases. If you don't, the following can happen:

Unity IAP re-invokes
```
OnPurchasePending
```
for the order on every subsequent
```
FetchPurchases
```
call or session start until you acknowledge it. Without your own de-duplication logic, this can grant the same item more than once.
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

ConfirmPurchase

when you have successfully persisted the purchase.

When returning

Pending

, 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.

Restore purchases

Enable users to regain access to previously owned products and subscriptions when they reinstall your app or switch devices. Understand how IAP retrieves a record of entitlements and grants access:

When a user reinstalls the application, Unity IAP restores owned products on the first
```
StoreController.FetchPurchases()
```
call.
IAP invokes the
```
OnPurchasesFetched
```
listener with an
```
Orders
```
object that includes all purchases (all states).
If the
```
PurchaseService.ProcessPendingOrdersOnPurchasesFetched
```
setting is set to
```
true
```
, IAP invokes the
```
OnPurchasePending
```
listener for each unfulfilled purchase.
Subsequent
```
FetchPurchases()
```
calls in the same session don't trigger
```
OnPurchasePending
```
for orders that you have already seen in the same session.

Use server-side validation alongside the SDK

You can make calls to the backend API while using the Unity In-App Purchases (IAP) SDK. This hybrid approach allows your server to act as the authority by validating transactions directly against Unity’s records before you reward the player. Unlike the standard backend API method, this doesn't require you to expose a public endpoint for webhooks, which can reduce your attack surface and simplify your server infrastructure.

Client-side implementation

When a purchase is initiated, the SDK returns a

PendingOrder

object. Extract the

OrderInfo.TransactionId

and pass it to your backend.

Backend authentication

Important

To make calls to the Unity IAP API, your backend must authenticate as a Service Account.

Use the Key ID and Secret Key from your Service Account to perform a Token Exchange to receive a stateless Bearer token. For more information, refer to how to Authenticate an API using a stateless token.

Refer to the following token exchange endpoint:


POST https://services.api.unity.com/auth/v1/token-exchange?projectId={projectId}&environmentId={envId}

Validate the order

Once your backend has a Bearer token, query the Unity IAP Order service with the following request:


GET https://iap.services.api.unity.com/v1/projects/{projectId}/environments/{envId}/orders/{orderId}

The

orderId

is the same as the

TransactionId

in the previous step. Refer to the following important response fields:

```
status
```
must be
```
paid
```
before you grant the items.
```
paymentProviderResourceId
```
contains the underlying Stripe Checkout Session ID, if you need it to cross-reference in the Stripe Dashboard.

Fulfill and complete the order

Refer to the following workflow to complete orders with server authority:

Verify that the status is paid and the productSku matches the expected item.
Update your player's database with the new entitlement.
After the backend returns a success code to the client, use one of the following methods to finalize the transaction in the Unity IAP system:
- Update the order directly with the API
- Make the client call
```
m_StoreController.ConfirmPurchase(order)
```
  .

For more information, refer to the section on how to Mark orders as fulfilled through the API.

Next steps

This page is part of a workflow to set up Direct-to-Consumer (D2C) payment providers with IAP. To continue this workflow, choose one of the following options:

Integrate D2C payment providers

Return to the Integrate D2C payment providers with IAP workflow page.

Test Stripe

Proceed to the next step in the workflow to set up your D2C payment provider.

Fulfill purchases through the SDK

Retrieve purchases

Determine purchase status

Purchase attributes

Attribute

Description

Purchase states

State

Description

Process purchases

Reflect purchase state in your UI

Non-consumables and subscriptions

Consumables

Update the button state during purchase flow

Callback

Description

Purchase acknowledgement and reliability

Acknowledge purchases persisted to the cloud

Restore purchases

Use server-side validation alongside the SDK

Client-side implementation

Backend authentication

Validate the order

Fulfill and complete the order

Next steps