Implement in-app purchases with Unity IAP APIs

Use Unity In-App Purchasing (IAP) APIs to initialize purchasing, map Microsoft Partner Center Store IDs to products that you want to sell, and handle purchases in your game.

Before you implement the purchase workflow, complete Set up Microsoft Partner Center and Unity Editor to install required packages and configure your products.

Important: Initialize the XGameRuntime before making any IAP calls. Unity IAPAbbreviation of Unity In App Purchase
See in Glossary requires this for Xbox support.

Follow these steps to implement purchases:

Initialize the purchasing system.
Define your products.
Retrieve detailed information for each product.
Retrieve existing purchases.
Handle purchase requests.
Confirm access to the purchased product.

1. Initialize the purchasing system

For more information, refer to the Unity IAP documentation on Initialize In-App Purchasing.

2. Define your products

For more information, refer to the Unity IAP documentation on Define products programmatically.

Note: Each product in Xbox Store has its own Store ID generated by Microsoft Partner Center when you create add-ons. Enter this ID into the ProductDefinition as the storeSpecificId.

Xbox Store only

If your game targets only Xbox Store, construct your ProductDefinition with the product’s Store ID as the storeSpecificId:

ICatalogProvider catalogProvider = new CatalogProvider(); 
var products = new List<ProductDefinition>
{ 
new("com.mygame.coins100", "9PEXAMPLE001", ProductType.Consumable), 
new("com.mygame.extralevel", "9NEXAMPLE002", ProductType.NonConsumable) 
};  
catalogProvider.AddProducts(products);

Multiple stores

If your game supports multiple stores and you want the same product on these stores, use the StoreSpecificIds mapping:

ICatalogProvider catalogProvider = new CatalogProvider(); 
var products = new List<ProductDefinition>
{  
   new("com.mygame.coins100", ProductType.Consumable),
   new("com.mygame.extralevel", ProductType.NonConsumable)
};
var coinIds = new StoreSpecificIds
{
   { "9PEXAMPLE001", XboxStore.Name }
};
var extraLevelIds = new StoreSpecificIds
{
   { "9NEXAMPLE002", XboxStore.Name }
};
var storeSpecificIds = new Dictionary<string, StoreSpecificIds>
{
   { "com.mygame.coins100", coinIds },
   { "com.mygame.extralevel", extraLevelIds }
};
catalogProvider.AddProducts(products, storeSpecificIds);

3. Retrieve detailed information for each product

For more information, refer to the IAP documentation on Fetch products.

Note: It’s recommended to fetch products using ICatalogProvider.FetchProducts, because the StoreSpecificIds are already mapped when you define products. If you want to fetch products using StoreController.FetchProducts, create different ProductDefinition lists per store. The following code example demonstrates how to create product lists based on the store:

var products = new List<ProductDefinition>();
var storeName = DefaultStoreHelper.GetDefaultStoreName();
if (storeName == XboxStore.Name)
{
   products.Add(new ProductDefinition("com.mygame.coins100", "9PEXAMPLE001", ProductType.Consumable));
   products.Add(new ProductDefinition("com.mygame.extralevel", "9NEXAMPLE002", ProductType.NonConsumable));
}
else
{
   products.Add(new ProductDefinition("com.mygame.coins100", ProductType.Consumable));
   products.Add(new ProductDefinition("com.mygame.extralevel", ProductType.NonConsumable));
}
var storeController = UnityIAPServices.StoreController();
storeController.FetchProducts(products);

4. Retrieve existing purchases

For more information, refer to the Unity IAP documentation on Fetch purchases.

5. Handle purchase requests

For more information, refer to the IAP documentation on Purchases.

6. Confirm access to the purchased product

Use entitlement checks to confirm that the user has valid access to the purchased product. For more information, refer to the Unity IAP API documentation on CheckEntitlement(Product).

After you complete the implementation, verify your purchase workflow in a sandbox environment.

Limitations

Unity IAP for Xbox Store doesn’t support the following features:

Subscription management: Users must manage their subscriptions through their Microsoft account.
Xbox Game Pass purchases: Xbox Game Pass related purchases aren’t available.
Multiple store support: Stores other than Xbox Store on Windows aren’t supported.
User account changes during gameplay: Unity IAP doesn’t update entitlements if the user changes accounts while the game is running. Re-initialize the purchasing system to retrieve products and purchases for the new user.

Additional resources

Set up Microsoft Partner Center and Unity Editor

Windows build settings reference