Initialize Unity IAP

Learn how to initialize the Unity IAP package, configure essential settings, and verify setup to start processing in‑app purchases across supported platforms.

Read time 5 minutes

Last updated 17 days ago

Before you use Unity In-App Purchasing (IAP), initialize the IAP package.

Important

If you want to integrate a Direct-to-Consumer (D2C) payment provider, there are some differences so refer to Initialize services to handle the startup sequence instead.

If you want to use Unity Analytics or Unity Authentication in your project, you need to initialize Unity Gaming Services (UGS) first before initializing IAP. Refer to the Initialize Unity Gaming Services section below for a how-to.

Initialize Unity Gaming Services

Call

UnityServices.InitializeAsync()

to initialize all Unity Gaming Services. This method returns a

Task

that you can use to track initialization progress. To learn more, refer to the Initialization example. For a fully functional sample, import the 06 Initialize Gaming Services sample (Package Manager > In-App Purchasing > Samples). For more information, refer to the Services Core API.

Initialize In-App Purchasing

Prerequisites

Choose one of the catalog setup methods in Create an IAP catalog to define the products you want to offer for purchase.

Initialization steps

Initialization consists of the following steps:

Getting a
```
StoreController
```
for your app store.
Attaching event listeners to the
```
StoreController
```
.
Connecting to your app store.
Fetching products from your app store.
Fetching purchases from your app store.


using System.Collections.Generic;using UnityEngine.Purchasing;public class MyIAPManager{    private StoreController m_StoreController;    public MyIAPManager()    {        // Define products        var catalogProvider = new CatalogProvider();        catalogProvider.AddProduct("100_gold_coins", ProductType.Consumable,            new StoreSpecificIds()            {                {"100_gold_coins_google", GooglePlay.Name},                {"100_gold_coins_mac", MacAppStore.Name}            });        // Get StoreController        m_StoreController = UnityIAPServices.StoreController();        // Add event listeners        m_StoreController.OnStoreDisconnected += OnStoreDisconnected;        m_StoreController.OnProductsFetched += OnProductsFetched;        m_StoreController.OnProductsFetchFailed += OnProductsFetchFailed;        m_StoreController.OnPurchasesFetched += OnPurchasesFetched;        m_StoreController.OnPurchasesFetchFailed += OnPurchasesFetchFailed;        // Connect to store        m_StoreController.Connect().ContinueWith(_ =>        {            // Fetch products from store            catalogProvider.FetchProducts(                list => m_StoreController.FetchProducts(list)                );        });    }    /// <summary>    /// Invoked when connection is lost to the current store, or on a Connect() failure.    /// </summary>    /// <param name="failure">Information regarding the failure.</param>    private void OnStoreDisconnected(StoreConnectionFailureDescription failure)    {    }    /// <summary>    /// Invoked with products that are successfully fetched.    /// </summary>    /// <param name="products">Products successfully returned from the app store.</param>    private void OnProductsFetched(List<Product> products)    {        // Fetch purchases for successfully retrieved products        m_StoreController.FetchPurchases();    }    /// <summary>    /// Invoked when an attempt to fetch products has failed or when a subset of products failed to be fetched.    /// </summary>    /// <param name="failure">Information regarding the failure.</param>    private void OnProductsFetchFailed(ProductFetchFailed failure)    {    }    /// <summary>    /// Invoked when previous purchases are fetched.    /// </summary>    /// <param name="orders">All active pending, completed, and deferred orders for previously fetched products.</param>    private void OnPurchasesFetched(Orders orders)    {    }    /// <summary>    /// Invoked when an attempt to fetch previous purchases has failed.    /// </summary>    /// <param name="failure">Information regarding the failure.</param>    private void OnPurchasesFetchFailed(PurchasesFetchFailureDescription failure)    {    }    /// <summary>    /// Invoked when a purchase needs to be processed and fulfilled.    /// </summary>    /// <param name="order">The order awaiting fulfillment.</param>    private void OnPurchasePending(PendingOrder order)    {    }}

Get a StoreController

StoreController

is the main interface for interacting with the In-App Purchasing functionality. You can get an instance of

StoreController

by calling UnityIAPServices.StoreController. It will return the default store controller or the specific store controller requested if a store name is provided.

Attach event handlers to the StoreController

For your store to function correctly, attach handlers to these events:

You may need to implement additional handlers as you integrate In-App Purchasing into your project. For a full list of events available through

StoreController

, refer to Events.

Connect to your app store

Call StoreController.Connect to connect to the app store. The returned

Task

resolves when the connection either completes or fails. A connection failure will invoke the

OnStoreDisconnected

event. You must be connected to the store before using any IAP functionality.

Fetch products

Note

Define your products in your catalog before fetching them. To choose a catalog setup method, refer to Create an IAP catalog.

To validate that your products are available for purchase, call StoreController.FetchProducts. Upon success, the

OnProductsFetched

event will be invoked with a list of successfully returned products.

OnProductsFetchFailed

will be invoked in the event of a failure. Purchases can only be fetched or initiated for products which have been successfully returned.

FetchProducts

can be called multiple times during runtime, but you must wait for any previous requests to finish before calling

FetchProducts

again. When using the Apple App Store,

OnPurchasePending

may be invoked for unprocessed orders after

FetchProducts

completes.

Fetch products from a catalog created in the Editor

The initialization steps example above defines products directly in code with

CatalogProvider

. If you instead defined your products using the IAP Catalog window in the Editor, follow these steps to fetch them:

Call
```
ProductCatalog.LoadDefaultCatalog
```
to load the catalog you created in the Editor.

Pass the catalog to

CodelessCatalogProvider.PopulateCatalogProvider

to get a

CatalogProvider

populated with your products.

The following example loads a catalog created in the Editor and populates a

CatalogProvider

with its products:


// Load the catalog created in the Editorvar catalog = ProductCatalog.LoadDefaultCatalog();var catalogProvider = CodelessCatalogProvider.PopulateCatalogProvider(catalog);

Use this

catalogProvider

in place of the one built with

CatalogProvider.AddProduct

in the initialization steps example above, then continue with

catalogProvider.FetchProducts

as shown.

GetProducts

GetProducts

and

FetchProducts

are not interchangeable. Make sure to call

FetchProducts

during initialization.

FetchProducts

will append resulting products to the list returned by

GetProducts

each time it is called.

Fetch purchases

Call

StoreController.FetchPurchases

to request your player's current active orders. Active orders include

PendingOrders

ConfirmedOrders

(active subscriptions and active non-consumables), and

DeferredOrders

. Refer to Purchases for more information. Calls to

FetchPurchases

will trigger one of two event handlers:

OnPurchasesFetched

, which will be invoked with an

Orders

object containing all Pending, Confirmed, and Deferred orders returned from the store or

OnPurchasesFetchFailed

, which will be invoked in the event of a failure. When using Google Play, this will invoke the

OnPurchasePending

event for any purchases which have not been processed. This is not strictly required to begin using In-App Purchasing functionality. However, it is recommended that you fetch and handle existing purchases before initiating new purchases, as you may encounter unexpected behavior otherwise. Note that if you fetch additional products during runtime, you will need to fetch purchases again.

Fetch purchases offline

Some platform libraries, such as Apple's StoreKit 2, cache entitlements on the device for offline access without caching product data. Although this approach isn't recommended, you can still call

FetchPurchases

after an

OnProductsFetchFailed

callback. In this case,

FetchPurchases

returns purchase information, but the linked products will have a

type

ProductType.Unknown

. Also, both

ProductDefinition.id

and

ProductDefinition.storeSpecificId

are set to the store-specific identifier.

Note

This doesn't apply to StoreKit 1. While StoreKit 1 caches the receipt on the device, the package requires fetched product data to parse receipt data. If product fetching fails,

FetchPurchases

doesn't return any purchase information.

GetPurchases

GetPurchases

and

FetchPurchases

are not interchangeable. Make sure to call

FetchPurchases

during initialization. Unlike

GetProducts

and

FetchProducts

FetchPurchases

not only populates the list returned by

GetPurchases

, but also overwrites it. Otherwise the package will try to keep it as synchronized as possible with the stores, based on order data from events.

Automatically initialize Codeless IAP

For instructions on how to set up Codeless IAP, refer to Set Up Codeless IAP.

Note

You should not enable auto-initialize if you also initialize manually in a script, as this may cause errors.

Automatic Unity Game Services initialization for Codeless IAP

If you are using the Codeless IAP, enable Unity Gaming Services automatic initialization by checking the Automatically initialize Unity Gaming Services checkbox at the bottom of the IAP Catalog window. This ensures that Unity Gaming Services initializes immediately when the application starts. To use this feature, Automatically initialize UnityIAPServices (recommended) must be enabled. If you do not see these checkboxes inside the IAP Catalog, it may be because you have not yet added products in the catalog window. This initializes Unity Gaming Services with the default initialization options. Some services require specific initialization options and might not work with the default configuration. If you need custom options, initialize Unity Gaming Services using the coded API described above.

Documentation

Development

User Acquisition

Monetization

Industry

Documentation

Development

User Acquisition

Monetization

Industry

In-App Purchasing

IAP Client API

IAP SDK API

Webshop Admin API

Webshop Client API

In-App Purchasing

Initialize Unity IAP

Initialize Unity Gaming Services

Initialize In-App Purchasing

Prerequisites

Initialization steps

Get a StoreController

Attach event handlers to the StoreController

Connect to your app store

Fetch products

Fetch products from a catalog created in the Editor

GetProducts

Fetch purchases

Fetch purchases offline

GetPurchases

Automatically initialize Codeless IAP

Automatic Unity Game Services initialization for Codeless IAP