Set up and initialize In-App Purchasing
Install the In-App Purchasing package and write the startup script that signs the player in, connects to your stores, and fetches your product catalog.
Read time 22 minutesLast updated 8 days ago
Unity In-App Purchasing (IAP) sells products through platform-native stores, such as the Apple App Store and Google Play, and through Direct-to-Consumer (D2C) payment providers, such as Stripe and Coda. Both paths share one setup: install the package, enable the service, and run a startup script that connects your application to the stores you sell through.
You can enable platform-native stores, D2C payment providers, or both. When you enable both, players choose how to pay through the Purchase Options UI.
The code on this page differs between versions of the IAP package. IAP 5.5 and later use one for every store, and IAP 5.4 uses one for each store.
PurchasingControllerStoreControllerPrerequisites
Before you begin, make sure you meet the following requirements:
- A Unity project that runs on a supported Unity version. Unity recommends Unity 6.0 or later, and supports Unity 2022.3 as the minimum version.
- Build support modules installed for each platform you target, such as Android Build Support or iOS Build Support.
- The In-App Purchasing package version 5.4 or later. To install it, refer to Install the In-App Purchasing package.
Install the In-App Purchasing package
To install the IAP package, follow these steps:
- In the Unity Editor, select Window > Package Management > Package Manager.
- Select the Unity Registry tab.
- Search for In-App Purchasing, or .
com.unity.purchasing - Select the package, then select Install.
Link your project and enable the IAP service
When you link your Unity project to a cloud project, the project gets the Unity Project ID that UGS requires at runtime.
Complete this task if you use the Remote Catalog, D2C payment providers, Unity Authentication, IAP analytics, a Google Play license key, or any other Unity service. A project that sells only through platform-native stores and defines its products in a local catalog can skip this step, but its transactions don't appear in IAP revenue reporting in the Unity Dashboard.
To link your project and enable IAP, follow these steps:
- In the Unity Editor, select Services > General Settings. Unity opens the Services General Settings page.
- Set Organization to your organization.
- Link a cloud project in one of the following ways:
- To use an existing cloud project, set Cloud project to that project, then select Link Unity project to cloud project.
- To create a new cloud project, select Create a new cloud project and follow the steps.
- Confirm that the Unity Project ID appears.
- Select Services > In-App Purchasing.
- Enable In-App Purchases.
- If you sell through Google Play, add your Google license key. For more information, refer to Add a Google license key to your project.
Linking your project to a cloud project and adding your Google license key lets Unity verify your Google Play transactions, so your revenue reporting counts them as verified. From In-App Purchasing 5.4.4, Android builds log a warning until you complete both.
Set your environment
The environment you select in the Unity Editor determines where IAP runs after you initialize UGS in code.
To set your environment, follow these steps:
- In the Unity Editor, select Edit > Project Settings > Services > Environments.
- Select the environment you want IAP to run in.
Choose how you define your products
Before you write your startup script, decide where your product definitions come from. Your choice determines which steps the script performs.
Catalog | When to use it | What the startup script does |
|---|---|---|
| Remote Catalog | Recommended for all projects, and required for D2C payment providers and webshops. You can update your products without shipping a build. | Signs the player in, connects to your stores, and fetches the catalog at runtime. |
| Local catalog | Projects that sell only through platform-native stores and ship a fixed product list with each build. | Connects to the store and fetches products from the catalog in the build. No sign-in. |
A local catalog still works. If you use one, you don't need the Remote Catalog steps on this page, and you can skip signing the player in. To display your transactions in IAP revenue reporting, still link your project and call in your startup script. Unity recommends that you import or migrate your catalog to the Remote Catalog service, because it lets you change prices and products between releases and is the only option that supports D2C payment providers and webshops.
UnityServices.InitializeAsync()Write the startup script
Your startup script performs the following steps in order:
- Initialize Unity Gaming Services.
- Set up Authentication event handlers.
- Sign the player in.
- Connect to each store you sell through.
- Fetch the Remote Catalog and pass its products to each store.
The following script initializes a project for platform-native stores and D2C payment providers at the same time. Each store has its own toggle, so you can enable either one or both. Attach the script to a GameObject in your first scene.
Select the tab for the version of the IAP package your project uses. IAP 5.5 and later use one for every store. IAP 5.4 uses one for each store.
PurchasingControllerStoreControllerusing System;using System.Collections.Generic;using System.Threading.Tasks;using Unity.Services.Authentication;using Unity.Services.Core;using UnityEngine;using UnityEngine.Purchasing;using UnityEngine.Purchasing.Extension;public class IapInitializer : MonoBehaviour{ // Native stores (App Store, Google Play) and IAP D2C Capabilities can run on their own or // together. With both on, the Purchase Options UI lets the player choose how to pay. [SerializeField] bool m_UseNative = true; [SerializeField] bool m_UseD2C = true; PurchasingController m_Controller; IPaymentOptionProvider m_PurchaseOptions; readonly IRemoteCatalogProvider m_Catalog = new RemoteCatalogProvider(); async void Start() { try { await SetUpAsync(); } catch (Exception e) { Debug.LogError($"In-App Purchasing setup failed: {e.Message}"); } } async Task SetUpAsync() { // 1. Initialize Unity Gaming Services. Skip steps 1 to 3 if your project // already does this. await UnityServices.InitializeAsync(); // 2. Attach the Authentication handlers before you sign the player in, so // that no event is missed. AuthenticationService.Instance.SignedIn += OnSignedIn; AuthenticationService.Instance.SignInFailed += OnSignInFailed; AuthenticationService.Instance.SignedOut += OnSignedOut; // 3. Sign in. The Remote Catalog and IAP D2C Capabilities need a signed-in player. // Replace anonymous sign-in with your own authentication: an anonymous player loses // their purchase history when the app is reinstalled or its data is cleared. if (!AuthenticationService.Instance.IsSignedIn) { await AuthenticationService.Instance.SignInAnonymouslyAsync(); } // 4. Create one PurchasingController for every store you sell through. var storeNames = new List<string>(); if (m_UseNative) { storeNames.Add(UnityIAPServices.GetDefaultStore()); } if (m_UseD2C) { storeNames.Add(PaymentProvider.Name); } if (storeNames.Count == 0) { Debug.LogWarning("Enable at least one store."); return; } m_Controller = new PurchasingController(storeNames.ToArray()); // Subscribe to every event before you call Connect(), or you lose the events // that fire first. One subscription covers every store on the controller. m_Controller.OnStoreDisconnected += OnStoreDisconnected; m_Controller.OnProductsFetched += OnProductsFetched; m_Controller.OnProductsFetchFailed += OnProductsFetchFailed; m_Controller.OnPurchasePending += OnPurchasePending; // Connects every store on the controller. await m_Controller.Connect(); m_PurchaseOptions = m_Controller.PaymentProvidersExtendedService?.GetPaymentOptionProviderUGUI(); // 5. One Remote Catalog works for every store. var result = await m_Catalog.FetchRemoteCatalog(); if (!result.Success) { Debug.LogError($"Could not fetch the Remote Catalog: {result.Exception?.Message}"); return; } // Each store fetches its own products, because each store has its own product IDs. foreach (var storeName in m_Controller.StoreNames) { m_Controller.FetchProductsWithNoRetries(m_Catalog.GetProducts(storeName), storeName); } } // Call this from your buy button. public async void Buy(string catalogListingId) { if (m_PurchaseOptions != null) { // This offers every store that has this listing: native, D2C, // and webshop. With a single option, it buys directly without // showing the picker. await m_PurchaseOptions.ShowPurchaseOption(catalogListingId); return; } // No D2C store, so buy from the native store. if (m_Controller != null && m_UseNative) { m_Controller.PurchaseProduct(catalogListingId, UnityIAPServices.GetDefaultStore()); } else { Debug.LogWarning($"No way to pay for {catalogListingId}."); } } // Every store's purchases arrive here, with the name of the store the player paid through. void OnPurchasePending(string storeName, PendingOrder order) { // Grant the content for the order here, then confirm it. // ConfirmPurchase sends the order back to its own store. m_Controller.ConfirmPurchase(order); } void OnProductsFetched(string storeName, List<Product> products) => Debug.Log($"{storeName}: {products.Count} products are ready to display."); void OnProductsFetchFailed(string storeName, ProductFetchFailed failure) => Debug.LogError($"{storeName}: product fetch failed: {failure.FailureReason}"); void OnStoreDisconnected(string storeName, StoreConnectionFailureDescription description) => Debug.LogError($"{storeName}: store disconnected: {description.message}"); void OnSignedIn() => Debug.Log($"Signed in as {AuthenticationService.Instance.PlayerId}."); void OnSignInFailed(RequestFailedException e) => Debug.LogError($"Sign-in failed: {e.Message}"); void OnSignedOut() => Debug.Log("Signed out."); void OnDestroy() { if (m_Controller != null) { m_Controller.OnStoreDisconnected -= OnStoreDisconnected; m_Controller.OnProductsFetched -= OnProductsFetched; m_Controller.OnProductsFetchFailed -= OnProductsFetchFailed; m_Controller.OnPurchasePending -= OnPurchasePending; } AuthenticationService.Instance.SignedIn -= OnSignedIn; AuthenticationService.Instance.SignInFailed -= OnSignInFailed; AuthenticationService.Instance.SignedOut -= OnSignedOut; }}
After the script runs, your application is connected to each store you enabled and holds the products from your catalog, so it can start a purchase.
The following details of the script might not be clear from the code sample alone:
- The script needs both and
using UnityEngine.Purchasing;.using UnityEngine.Purchasing.Extension;andRemoteCatalogProviderare in different namespaces, and if you omit either directive, the type doesn't resolve.IRemoteCatalogProvider - The script initializes IAP in rather than
Start, because it awaits UGS initialization and sign-in, which can't complete inAwake.Awake - The guard covers a sign-in that's already complete, but not one that's still in progress.
IsSignedInthrows in both cases, so a project that signs players in elsewhere must remove steps 1 to 3 instead of relying on the guard.SignInAnonymouslyAsync - The script doesn't cover a change of signed-in player, because anonymous sign-in keeps the same player for the session. If players can switch accounts while your application runs, attach an handler and re-fetch from the store that raises it. Refer to Handle an account change.
OnAuthAccountChanged
Connect to your stores
A controller is the main interface for IAP functionality. The store name you pass is the only difference between the two kinds of store:
- For platform-native stores, use the default store for the platform your application runs on.
- For D2C payment providers, use .
PaymentProvider.Name
Attach handlers to the controller's events before you call , or you lose the events that fire during connection. You must connect to a store before you use any other IAP functionality on it.
ConnectPurchasingControllerUnityIAPServices.GetDefaultStore()A project that sells through both creates one controller with both names, , and keeps it for the lifetime of the application. A project that sells through one store passes only that name. For more information about how the controller routes each call to a store, refer to Introduction to the purchasing controller.
new PurchasingController(UnityIAPServices.GetDefaultStore(), PaymentProvider.Name)The constructor throws an if you pass no store name, an empty name, or the same name twice, and a if a name isn't a registered store. After you create the controller, its methods don't throw. They log an error and report the problem through the usual failure event instead.
ArgumentExceptionStoreExceptionOne subscription covers every store on the controller, and each event passes the name of the store it comes from as its first parameter. Attach handlers to the following events at minimum:
ConnectTaskOnStoreDisconnectedConnect(PaymentProvider.Name)PurchasingControllerFetch the Remote Catalog
Instantiate a and call to retrieve your products from the Remote Catalog service. One provider serves every store: the Remote Catalog maps each listing to the native store IDs it carries, so the same fetch supplies a native store and a D2C payment provider in the same application.
RemoteCatalogProviderFetchRemoteCatalogEach store fetches its own products, because a product definition holds the product ID of one store. For each store on the controller, call on the catalog provider with the name of that store, which returns the definitions with that store's product IDs. Pass them to with the same store name:
GetProductsFetchProductsWithNoRetriesforeach (var storeName in m_Controller.StoreNames){ m_Controller.FetchProductsWithNoRetries(m_Catalog.GetProducts(storeName), storeName);}
The catalog provider reuses one list of definitions for every store, and rewrites its product IDs for the store you name. The controller gives each store its own copy of the definitions, so the next call doesn't change the products of the previous store.
GetProductsYou can call more than once at runtime, but wait for each call to finish before you make the next one. appends its results to the list that returns, so the two methods aren't interchangeable. Call during initialization.
FetchProductsFetchProductsGetProductsFetchProductsFetch products from a catalog created in the Editor
If you define your products with the IAP Catalog window instead of the Remote Catalog, replace the in the script with a built from the local catalog:
RemoteCatalogProviderCatalogProvider// Load the catalog created in the Editor.ProductCatalog catalog = ProductCatalog.LoadDefaultCatalog();CatalogProvider catalogProvider = CodelessCatalogProvider.PopulateCatalogProvider(catalog);
ProductCatalog.LoadDefaultCatalogCodelessCatalogProvider.PopulateCatalogProviderCatalogProviderRemoteCatalogProviderA local catalog doesn't support D2C payment providers.
Fetch purchases
Call to request the player's active orders, which include pending, confirmed, and deferred orders. Add the call to , so that it runs after the store returns your products. On a , pass the store name the event gives you, , so that each store fetches its purchases after it returns your products. Without a store name, fetches from every store on the controller. In IAP 5.4, call on each instead.
FetchPurchasesOnProductsFetchedPurchasingControllerFetchPurchases(storeName)FetchPurchasesStoreController.FetchPurchasesStoreControllerThis step isn't required to start using IAP, but Unity recommends that you fetch and handle existing purchases before you initiate new ones. Fetch purchases again whenever you fetch additional products at runtime.
FetchPurchasesOnPurchasesFetchedOrdersOnPurchasesFetchFailedPurchasingControllerOnPurchasePendingOnPurchasePendingFetchProductsUnlike , overwrites the list that returns rather than appending to it. For more information, refer to Purchases.
FetchProductsFetchPurchasesGetPurchasesHandle an account change
When the signed-in player changes while your application runs, Unity IAP raises once for each store you connect to. In IAP 5.4, each raises instead. This event requires the Unity Authentication package () version 3.0.0 or later.
OnAuthAccountChangedStoreControllerStoreController.OnAuthAccountChangedcom.unity.services.authenticationA project that sells through both a platform-native store and a direct-to-consumer payment provider receives the event twice, once for each store.
On the Apple App Store, Unity IAP also clears the product details that and return. If a product fetch is in progress when the account changes, Unity IAP fails that fetch instead of caching the previous player's results against the new account.
GetProductDetailsGetIntroductoryPriceDictionaryDon't read or in your handler, because Unity IAP has already emptied both.
GetProductsGetPurchasesA handler you attach to the applies to every store on it, so every store clears its caches. From your handler, fetch products and purchases from the store the event names, in the same order as at startup:
PurchasingController- Fetch your catalog.
- Call with the store name the event gives you.
FetchProducts - If your application fetches purchases, let your handler call
OnProductsFetchedwith the store name, as described in Fetch purchases. The store then fetches purchases after it has the new player's products.FetchPurchases
// With the other subscriptions, before you call Connect():m_Controller.OnAuthAccountChanged += OnAuthAccountChanged;// In OnDestroy, with the other unsubscriptions:m_Controller.OnAuthAccountChanged -= OnAuthAccountChanged;async void OnAuthAccountChanged(string storeName){ // A provider for this store's refetch only, so each store's handler fetches its own catalog. var catalog = new RemoteCatalogProvider(); var result = await catalog.FetchRemoteCatalog(); if (!result.Success) { Debug.LogError($"Could not fetch the Remote Catalog: {result.Exception?.Message}"); return; } m_Controller.FetchProductsWithNoRetries(catalog.GetProducts(storeName), storeName); // If you fetch purchases, call FetchPurchases(storeName) from OnProductsFetched, // as described in Fetch purchases, so this store has its products first.}
Because the event fires once for each store, a project with two stores fetches the catalog twice. Both fetches return the same catalog, so the second one is redundant but harmless.
Start a purchase
Call from your buy button, with the of the listing you want to sell.
BuycatalogListingIdWhen you enable D2C payment providers, shows the Purchase Options UI, which presents every way the player can pay for that listing: the platform-native store, an eligible D2C payment provider, and a webshop if the listing has one. If only one option is available, the Purchase Options UI skips the choice and completes the purchase through that option. When you don't enable D2C payment providers, sends the purchase to the platform-native store.
BuyBuyA completed purchase from any store arrives on the controller's event, with the name of the store the player paid through. Grant the player their content in , then call to close the order. sends the order to the store it belongs to, which holds, so one handler confirms the orders of every store.
OnPurchasePendingOnPurchasePendingConfirmPurchaseConfirmPurchaseOrder.StoreNameIn IAP 5.4, a completed purchase arrives on the of the store the player paid through, so each controller handles and confirms its own orders.
StoreControllerFor more information, refer to Fulfill purchases through the SDK.