Develop

Add-ons Integration

Updated: May 17, 2025

This topic discusses how to integrate add-ons into your app.

For an overview of add-ons, see Add-ons (DLC and IAP).

For guidance on setting up add-ons, see Setting Up Add-ons.

For best practices and other considerations, see Working with Add-ons.

For details on server-to-server APIs, see IAP Server-to-Server APIs.

For guidance on testing, see Testing Add-ons.

For IAP consumable item behavior, see Consuming Purchased IAP Items.

Requirements

You must complete a few requirements first in order to integrate add-ons with your application. The following sections outline how to satisfy the prerequisites.

You must have at least one version of your APK uploaded to the Developer Dashboard before you can use the Monetization API. In addition to setting up the app, you must upload a valid APK package so the system can verify your app's identity and correctly associate it with the Monetization API.

Setting up items for purchase

Before you begin integrating add-ons in your app, you need to define the items that you will be offering for purchase. For guidance on setting up add-ons, see Setting Up Add-ons.

Indicate that the app needs an internet connection

For add-ons associated with downloadable content, mark your app as requiring an internet connection.

From the Developer Dashboard⁠, select your app.

Choose your app in the Developer Dashboard

From the left nav, go to Distribution > App Submissions.

Developer Dashboard menu options: Distribution and App submission

From the App Submissions page, click on the latest version of your app.

The app submissions page in the Developer Dashboard

Click the App Metadata tab.

The App Metadata tab in the Developer Dashboard

Click the Specs tab.

The Specs tab in the Developer Dashboard

Scroll down to find the Internet Connection dropdown menu. From this menu, select Internet connection required.

The Internet Connection dropdown menu in the Developer Dashboard

Enable in-app purchases

The following steps show how to enable in-app purchases. Enabling this feature requires access to a player’s User ID.

From the Developer Dashboard⁠, select your app.

From the left nav, go to Requirements > Data Use Checkup.

Requirements and Data Use Checkup in the Developer Dashboard

In the Age group self-certification section, click Start.

Age group certification window in the Developer Dashboard

In the window that appears, select the age group that best describes your app, then click Continue.

In the Request to access platform features section, click the Add button next to User ID. A new window will open.

Data Use Checkup window in the Developer Dashboard

In the User ID window:

Choose Use Add-ons: Downloadable Content and In-App Purchases Commerce (IAP) from the Usage dropdown menu.

Enter a detailed Description of how you will use the User ID.

(Optional) Add any supporting screenshots that further indicate your usage.

Click the checkbox to agree to Meta terms and policies.

Click Add to Request.

User ID details window in the Developer Dashboard

Back in the Request to access platform features section, click the Add button next to In-App Purchases and/or downloadable content. A new window will open.

In the In-App Purchases window:

Choose Use Add-ons: Downloadable Content and In-App Purchases Commerce (IAP) from the Usage dropdown menu.

Enter a detailed Description of how you will use in-app purchases.

(Optional) Add any supporting screenshots that further indicate your usage.

Click the checkbox to agree to Meta terms and policies including without limitation the Developer Data Use Policy.

Click Add to Request.

In-App Purchases details window in the Developer Dashboard

In the Data Use Checkup window, click Submit Requests (2).

Submit Requests button in the Data Use Checkup window in the Developer Dashboard

After submitting your requests, a new window will appear. Answer all of the questions in the Data handling section and click Next.

Data handling section in the Data Use Checkup window in the Developer Dashboard

On the Review requests page, make sure that User ID and In-App Purchases and/or downloadable content are listed under Added in the Your requests section. Click Next.

Review requests in the Data Use Checkup window in the Developer Dashboard

On the Submit page, click Submit for review.

Submit button in the Data Use Checkup window in the Developer Dashboard

Integrating with add-ons

This section describes how you can offer assets that you’ve built as in-app purchases.

The following SDK methods can be called from your client app. Detail about each function can be found in the Platform SDK Reference Content.

Retrieve a list of available items and prices by SKU

To retrieve a list of add-on items that are available to the user to purchase by SKU, use the following method. The SKUs must have a description to be retrieved by this method.

This method also returns any virtual SKUs associated with subscription periods.

ovr_IAP_GetProductsBySKU()

If your app displays a price for any add-on, you should use the localized price returned from this endpoint. Do not hard-code price amounts inside the app.

SKUs for subscriptions

If a subscription tier only has a single subscription period, you can reference that single subscription period as an add-on using the SKU of its tier.

However, to differentiate between multiple subscription periods of the same SKU, we create a virtual SKU for each period by appending the subscription period (WEEKLY, BIWEEKLY, MONTHLY, QUARTERLY, SEMIANNUAL, ANNUAL) to the SKU in this format:

<SKU>:SUBSCRIPTION__<PERIOD>

For example, consider a subscription tier with the SKU MyApp-Subscription that has both monthly and annual subscription periods. You would reference the subscription add-on items by virtual SKU as follows:

MyApp-Subscription:SUBSCRIPTION__MONTHLY

MyApp-Subscription:SUBSCRIPTION__ANNUAL

The GetProductsBySKU method also returns virtual SKUs, so to prevent errors, we recommend you call that method to obtain the full list of available SKUs instead of hardcoding virtual SKU strings into your product.

For more information, see Subscriptions.

Launch the checkout flow for a SKU

To launch the checkout flow for a user to complete the purchase of a specified SKU, use the following method.

ovr_IAP_LaunchCheckoutFlow()

Retrieve all of the user’s purchased items

To retrieve a list of in-app purchases that the user has made, use the following method. The returned list includes all durable type purchases and any consumable type purchases that have not been consumed.

ovr_IAP_GetViewerPurchases()

Retrieve a cached list of durable items a user has purchased

To retrieve a list of durable add-on items that the user has purchased, use the following method. The returned list contains non-consumable purchases and is populated from the device cache. You should always use GetViewerPurchases first and then this method if the other call fails.

ovr_IAP_GetViewerPurchasesDurableCache()

Consume a purchased item

To consume a purchased item on behalf of a user, which marks the item as used in the app, use the following method.

ovr_IAP_ConsumePurchase()

Integrating with downloadable content

The following methods allow you to integrate downloadable content (DLC) with your app. Use these methods to retrieve, download, and manage asset files associated with your app.

Get a list of assets associated with an app

At app startup, this method gets a list of all the assets associated with the app.

ovr_AssetFile_GetList()

This method returns a list of available asset details. Each item in the array has the following properties:

assetFileName - the file name,

assetFileID - Asset identifier

IapStatus, which is one of the following values: free, entitled, or not-entitled

downloadStatus, which is one of the following values:

installed meaning that user has installed the file

available meaning that user can download the file

in-progress meaning the file is being downloaded or is installing for that user.

Initiate downloads

If there is a file that is available to download, meaning its status is free or entitled, and download_status = available, you can initiate the download by calling:

ovr_AssetFile_DownloadById()

To make this call, pass the ID of the item as returned by the initial GetList call.

When you make this call, you will receive an immediate DownloadResult response with the path to the asset as a confirmation that the request was successful. You should also listen for DownloadUpdate notifications which return info about transferred bytes, and a complete flag that notifies you when the download is complete.