IAP Module

Back To Top

In-App Purchases Module

A Microsoft Store game can have several In-App Purchases. Inside the Partner Center these are referred to as add-ons and can be of multiple types (consumables, durables, subscriptions, DLCs). For detailed instructions on how to configure those, check the Add-ons section on the Microsoft Partner Center Helpdesk page. Contents of this module can be divided into the following sections:

Product Functions

The following functions are provided for working with products:

• ms_iap_AcquireLicenseForDurables
• ms_iap_ReleaseLicenseForDurables
• ms_iap_CanAcquireLicenseForStoreId
• ms_iap_QueryAddOnLicenses
• ms_iap_QueryAssociatedProducts
• ms_iap_QueryConsumableBalanceRemaining
• ms_iap_QueryEntitledProducts
• ms_iap_QueryGameLicense
• ms_iap_QueryProductForCurrentGame
• ms_iap_QueryProductForPackage
• ms_iap_QueryProducts
• ms_iap_ReportConsumableFulfillment
• ms_iap_ShowAssociatedProductsUI
• ms_iap_ShowProductPageUI
• ms_iap_ShowPurchaseUI
• ms_iap_ShowRateAndReviewUI
• ms_iap_ShowRedeemTokenUI

Package Functions

The following functions are provided for working with packages (DLCs):

• ms_iap_AcquireLicenseForPackage
• ms_iap_ReleaseLicenseForPackage
• ms_iap_CanAcquireLicenseForPackage
• ms_iap_DownloadAndInstallPackages
• ms_iap_EnumeratePackages
• ms_iap_MountPackage
• ms_iap_UnmountPackage

Constants

The following constants (enumerations) are used as filter arguments and return values for some API queries:

• Package Kinds
• Package Scopes
• Product Kinds

Structs

Some of the API asynchronous callback responses return data in the form of structs. This sections aims to deliver detailed information on each of the structs used within the In-App Purchases Module context. The following structs (structures) are used as return members of API function calls:

• Addon License Details
• Package Details
• Product Details

---

Back To Top

ms_iap_AcquireLicenseForDurables

This function acquires a license for the current game's specified durable that the user is entitled to. This is only applicable to Durable without package add-on types. For Durable with packages (DLC) type, use ms_iap_AcquireLicenseForPackage instead. This is an asynchronous function that will trigger the Async In-App Purchase event when the task is finished.

Syntax:

ms_iap_AcquireLicenseForDurables(user_id, store_id);

Argument	Type	Description
user_id	pointer	The user ID to use in the store context.
store_id	string	The store ID of the product.

Returns:

Real (In-App Purchase Request ID)

Triggers:

Asynchronous In-App Purchase Event

Key	Type	Description
type	string	The constant "ms_iap_AcquireLicenseForDurables_result"
id	real	The asynchronous request ID.
status	bool	Whether or not the asynchronous request succeeded.
store_id	string	The store ID used when acquiring the license.

Example:

var _userId = xboxone_get_activating_user();
var _storeId = global.products[0].storeId;

requestId = ms_iap_AcquireLicenseForDurables(_userId, _storeId);

In the code above first we get the user ID (_userId) of the activating user and we get the store ID (_storeId) of the product we want to acquire the license to (note that for convenience we keep the products stored in a global variable). The function call will then return a request ID (requestId) that can be used inside an Async In-App Purchase event.

if (async_load[? "type"] == "ms_iap_AcquireLicenseForDurables_result")
{
    if (async_load[? "id"] == requestId)
    {
        if (async_load[? "status"])
        {
            show_debug_message("License successfully acquired!");
        }
    }
}

The code above matches the response against the correct event type and id , providing a success message if status is true.

---

Back To Top

ms_iap_AcquireLicenseForPackage

Acquires a license for the current game's specified DLC that the user is entitled to use. This is only applicable to Durable with package add-on type. For Durable type, use ms_iap_AcquireLicenseForDurables instead. This is an asynchronous function that will trigger the Async In-App Purchase event when the task is finished.

Syntax:

ms_iap_AcquireLicenseForPackage(user_id, package_id);

Argument	Type	Description
user_id	pointer	The user ID to use in the store context.
package_id	string	A string that uniquely identifies a store package.

Returns:

Real (In-App Purchase Request ID)

Triggers:

Asynchronous In-App Purchase Event

Key	Type	Description
type	string	The constant "ms_iap_AcquireLicenseForPackage_result"
id	real	The asynchronous request ID.
status	bool	Whether or not the asynchronous request succeeded.
package_id	string	The package ID used when acquiring the license.

Example:

var _userId = xboxone_get_activating_user();
var _packageId = global.packages[0].packageId;

requestId = ms_iap_AcquireLicenseForPackage(_userId, _storeId);

In the code above first we get the user ID (_userId) of the activating user and we get the package ID (_packageId) of the product we want to acquire the license to (note that for convenience we keep the products stored in a global variable). The function call will then return a request ID (requestId) that can be used inside an Async In-App Purchase event.

if (async_load[? "type"] == "ms_iap_AcquireLicenseForPackage_result")
{
    if (async_load[? "id"] == requestId)
    {
        if (async_load[? "status"])
        {
            show_debug_message("License for package successfully acquired!");
        }
    }
}

The code above matches the response against the correct event type and id , providing a success message if status is true.

---

Back To Top

ms_iap_CanAcquireLicenseForPackage

This function provides the ability for a game to determine if the user could acquire a license for a particular piece of content without actually acquiring that license and using up that user's concurrency slot. This cannot be used for the current base game (since it has a license already), but to determine if the user owns some DLC for that game. This is an asynchronous function that will trigger the Async In-App Purchase event when it is finished.

Syntax:

ms_iap_CanAcquireLicenseForPackage(user_id, package_id);

Argument	Type	Description
user_id	pointer	The user ID to use in the store context.
package_id	string	A string that uniquely identifies a store package.

Returns:

Real (In-App Purchase Request ID)

Triggers:

Asynchronous In-App Purchase Event

Key	Type	Description
type	string	The string value "ms_iap_CanAcquireLicenseForPackage_result".
async_id	real	The asynchronous request ID.
async_status	bool	Whether or not the asynchronous request succeeded.
package_id	string	A string that uniquely identifies a store package.
licensableSku	string	The SKU the user would be able to license.
licenseStatus	integer	Indicates if a user would be able to license a package: 0 - The package is not licensable to the user. 1 - The package is licensable to the user. 2 - The product is not individually licensable.

Example:

var _userId = xboxone_get_activating_user();
var _storeId = global.products[0].storeId;

requestId = ms_iap_AcquireLicenseForDurables(_userId, _storeId);

In the code above first we get the user ID (_userId) of the activating user and we get the store ID (_storeId) of the product we want to acquire the license to (note that for convenience we keep the products stored in a global variable). The function call will then return a request ID (requestId) that can be used inside an Async In-App Purchase event.

if (async_load[? "type"] == "ms_iap_CanAcquireLicenseForPackage_result")
{
    if (async_load[? "async_id"] == requestId)
    {
        if (async_load[? "licensableStatus"] == 1)
        {
            show_debug_message("The product is licensable!");
        }
    }
}

The code above matches the response against the correct event type and async_id , printing to the debug console if the current product is licensable to the provided user.

---

Back To Top

ms_iap_CanAcquireLicenseForStoreId

This function provides the ability for a game to determine if the user could acquire a license for a particular piece of content without actually acquiring that license and using up that user's concurrency slot. This is not used for the currently running game (since it has a license already), but to determine if the user owns other games from the same publisher, either to up-sell or to provide special benefits to loyal fans. For example: this could be used by a racing game to determine whether to give bonus cars to users who owned prior versions of the game. This function is also used to determine whether or not the game should show content in its in game store based on whether or not the user already owns some content. This is an asynchronous function that will trigger the Async In-App Purchase event when it is finished.

Syntax:

ms_iap_CanAcquireLicenseForStoreId(user_id, store_id);

Argument	Type	Description
user_id	pointer	The user ID to use in the store context.
store_id	string	The store ID of the product to check the license status.

Returns:

Real (In-App Purchase Request ID)

Triggers:

Asynchronous In-App Purchase Event

Key	Type	Description
type	string	The string value "ms_iap_CanAcquireLicenseForStoreId_result".
async_id	real	The asynchronous request ID.
async_status	bool	Whether or not the asynchronous request succeeded.
store_id	string	The store ID of the product being checked.
licensableSku	string	The SKU the user would be able to license.
licenseStatus	integer	Indicates if a user would be able to license a package: 0 - The package is not licensable to the user. 1 - The package is licensable to the user. 2 - The product is not individually licensable.

Example:

var _userId = xboxone_get_activating_user();
var _storeId = global.products[0].storeId;

requestId = ms_iap_AcquireLicenseForDurables(_userId, _storeId);

In the code above first we get the user ID (_userId) of the activating user and we get the store ID (_storeId) of the product we want to acquire the license to (note that for convenience we keep the products stored in a global variable). The function call will then return a request ID (requestId) that can be used inside an Async In-App Purchase event.

if (async_load[? "type"] == "ms_iap_CanAcquireLicenseForStoreId_result")
{
    if (async_load[? "async_id"] == requestId)
    {
        if (async_load[? "licensableStatus"] == 1)
        {
            show_debug_message("The product is licensable!");
        }
    }
}

The code above matches the response against the correct event type and async_id , printing to the debug console if the current product is licensable to the provided user.

---

Back To Top

ms_iap_DownloadAndInstallPackages

Downloads and installs the specified store packages. This is an asynchronous function that will trigger the Async In-App Purchase event when it is finished. The async completion message will only be raised when the package is actually installed (not just registered).

Syntax:

ms_iap_DownloadAndInstallPackages(user_id, package_ids);

Argument	Type	Description
user_id	pointer	The user ID to use in the store context.
package_ids	string[]	An array of strings that uniquely identify the store packages.

Returns:

Real (In-App Purchase Request ID)

Triggers:

Asynchronous In-App Purchase Event

Key	Type	Description
type	string	The string value "ms_iap_DownloadAndInstallPackages_result".
id	real	The asynchronous request ID.
status	bool	Whether or not the asynchronous request succeeded.
package_ids	string[]	An array of strings that uniquely identify the store packages.

Example:

var _userId = xboxone_get_activating_user();
var _package1 = global.package[0].packageId;
var _package2 = global.package[1].packageId;
var _package2 = global.package[2].packageId;

requestId = ms_iap_AcquireLicenseForDurables(_userId, [_package1, _package2, _package3]);

In the code above first we get the user ID (_userId) of the activating user and after that we execute the function passing in an array of packages to be downloaded and installed. The function call will then return a request ID (requestId) that can be used inside an Async In-App Purchase event.

if (async_load[? "type"] == "ms_iap_DownloadAndInstallPackages_result")
{
    if (async_load[? "id"] == requestId)
    {
        if (async_load[? "status"] == 1)
        {
            show_debug_message(async_load[? "package_ids"]);
        }
    }
}

The code above matches the response against the correct event type and id , printing to the debug console an array will all the installed packages IDs.

---

Back To Top

ms_iap_EnumeratePackages

This functions enumerates the results of a package query. This is an asynchronous function that will trigger the Async In-App Purchase event when the task is finished.

Syntax:

ms_iap_EnumeratePackages(package_kind, scope);

Argument	Type	Description
package_kind	constant	The value that indicates whether to enumerate app packages or content packages (see Package Kinds).
scope	constant	The scope of the installation packages (see Package Scopes ).

Returns:

Real (In-App Purchase Request ID)

Triggers:

Asynchronous In-App Purchase Event

Key	Type	Description
type	string	The string value "ms_iap_EnumeratePackages_result".
id	real	The asynchronous request ID.
status	bool	Whether or not the asynchronous request succeeded.
results	array	An array of Package Details structs.

Example:

requestId = ms_iap_EnumeratePackages(e_ms_iap_PackageKind_Content, e_ms_iap_PackageEnumerationScope_ThisOnly);

In the code above first we request an enumeration all the packages of type content (e_ms_iap_PackageKind_Content) and whose scope is limited to the current game (e_ms_iap_PackageEnumerationScope_ThisOnly). The function call will then return a request ID (requestId) that can be used inside an Async In-App Purchase event.

if (async_load[? "type"] == "ms_iap_EnumeratePackages_result")
{
    if (async_load[? "id"] == requestId)
    {
        if (async_load[? "status"] == 1)
        {
            show_debug_message(async_load[? "results"]);
        }
    }
}

The code above matches the response against the correct event type and id , printing to the debug console an array will all the Package Details structs.

---

Back To Top

ms_iap_MountPackage

This function mounts the installation of specified content. This is an asynchronous function that will trigger the Async In-App Purchase event when it is finished.

Syntax:

ms_iap_MountPackage(package_id);

Argument	Type	Description
package_id	string	A string that uniquely identifies the installed package on the disk. Pass in the packageIdentifier field from the Package Details struct returned from the ms_iap_EnumeratePackages async callback.

Returns:

Real (In-App Purchase Request ID)

Triggers:

Asynchronous In-App Purchase Event

Key	Type	Description
type	string	The string value "ms_iap_MountPackage_result".
id	real	The asynchronous request ID.
package_id	string	A string that uniquely identifies the installed package on the disk.
mount_path	string	The path to the mounted installation.

Example:

var _package = global.package[0].packageId;

requestId = ms_iap_MountPackage(_package);

In the code above first we get the user ID (_userId) of the activating user and after that we execute the function passing in an array of packages to be downloaded and installed. The function call will then return a request ID (requestId) that can be used inside an Async In-App Purchase event.

if (async_load[? "type"] == "ms_iap_MountPackage_result")
{
    if (async_load[? "id"] == requestId)
    {
        show_debug_message("Package ID: " + async_load[? "package_id"]);
        show_debug_message("Mount Path: " + async_load[? "mount_path"]);
    }
}

The code above matches the response against the correct event type and id , printing to the debug console the current packages ID and it's mount path on disk.

---

Back To Top

ms_iap_QueryAddOnLicenses

Retrieves the licenses the user was granted for Add-ons (also known as a durable without bits) of the currently running game. It is generally recommended to use dlc, rather than add-ons, but this API exists for the few that choose to use add-ons anyways. Add-ons are typically content or features that require a purchase to unlock but don't require a download because they are built into the game. They do not work for games that have discs, or may ever have discs. This is an asynchronous function that will trigger the Async In-App Purchase event when it is finished.

Syntax:

ms_iap_QueryAddOnLicenses(user_id);

Argument	Type	Description
user_id	pointer	The user ID to use in the store context.

Returns:

Real (In-App Purchase Request ID)

Triggers:

Asynchronous In-App Purchase Event

Key	Type	Description
type	string	The constant "ms_iap_QueryAddOnLicenses_result"
id	real	The asynchronous request ID.
status	bool	Whether or not the asynchronous request succeeded.
result	array	An array of Addon License Details structs.

Example:

var _userId = xboxone_get_activating_user();

requestId = ms_iap_QueryAddOnLicenses(_userId);

In the code above first we get the user ID (_userId) of the activating user and we call the function with it. The function call will then return a request ID (requestId) that can be used inside an Async In-App Purchase event.

if (async_load[? "type"] == "ms_iap_QueryAddOnLicenses_result")
{
    if (async_load[? "id"] == requestId)
    {
        if (async_load[? "status"])
        {
            show_debug_message(async_load[? "result"]);
        }
    }
}

The code above matches the response against the correct event type and id , printing to the debug console if the result of the query; an array of Addon License Details structs.

---

Back To Top

ms_iap_QueryAssociatedProducts

Gets store listing information for the products that can be purchased from within the current game. This API will only return products that can be browsed within the store including any Add-on products that do not have a store page as long as they are not expired. Any product that is hidden, expired, or taken down from the store will not be returned in the results from this API. If you need store info from a hidden, expired, or taken down product use the ms_iap_QueryProducts passing in the product's StoreID. This is an asynchronous function that will trigger the Async In-App Purchase event when it is finished.

Syntax:

ms_iap_QueryAssociatedProducts(user_id, product_kinds);

Argument	Type	Description
user_id	pointer	The user ID to use in the store context.
product_kinds	constant	The type of products to return. For more information read the Product Kinds section.

Returns:

Real (In-App Purchase Request ID)

Triggers:

Asynchronous In-App Purchase Event

Key	Type	Description
type	string	The constant "ms_iap_AcquireLicenseForDurables_result"
id	real	The asynchronous request ID.
status	bool	Whether or not the asynchronous request succeeded.
results	array	An array of Product Details structs.

Example:

var _userId = xboxone_get_activating_user();
var _product_kinds = e_ms_iap_ProductKind_Consumable;

requestId = ms_iap_QueryAssociatedProducts(_userId, _product_kinds);

In the code above first we get the user ID (_userId) of the activating user, afterwards we create a filter for consumable products (_product_kinds) and we call the function with both arguments. The function call will then return a request ID (requestId) that can be used inside an Async In-App Purchase event.

if (async_load[? "type"] == "ms_iap_QueryAssociatedProducts_result")
{
    if (async_load[? "id"] == requestId)
    {
        if (async_load[? "status"])
        {
            show_debug_message(async_load[? "result"]);
        }
    }
}

The code above matches the response against the correct event type and id , printing to the debug console the result of the query; an array of Product Details structs.

---

Back To Top

ms_iap_QueryConsumableBalanceRemaining

This function gets the consumable balance remaining for the specified product ID. This is an asynchronous function that will trigger the Async In-App Purchase event when it is finished.

Syntax:

ms_iap_QueryConsumableBalanceRemaining(user_id, store_id);

Argument	Type	Description
user_id	pointer	The user ID to use in the store context.
store_id	string	The ID of the consumable to retrieve the balance for.

Returns:

Real (In-App Purchase Request ID)

Triggers:

Asynchronous In-App Purchase Event

Key	Type	Description
type	string	The constant "ms_iap_QueryConsumableBalanceRemaining_result"
id	real	The asynchronous request ID.
status	bool	Whether or not the asynchronous request succeeded.
store_id	string	The ID of the consumable to retrieve the balance for.
quantity	real	The remaining quantity of the consumable.

Example:

var _userId = xboxone_get_activating_user();
var _storeId = global.products[3].storeId;

requestId = ms_iap_QueryConsumableBalanceRemaining(_userId, _storeId);

In the code above first we get the user ID (_userId) of the activating user and we get the store ID (_storeId) of the product we want to query the balance for (note that for convenience we keep the products stored in a global variable). The function call will then return a request ID (requestId) that can be used inside an Async In-App Purchase event.

if (async_load[? "type"] == "ms_iap_QueryConsumableBalanceRemaining_result")
{
    if (async_load[? "id"] == requestId)
    {
        if (async_load[? "status"])
        {
            var _quantity = async_load[? "quantity"];
            show_debug_message("Amount of potions left: " + string(_quantity));
        }
    }
}

The code above matches the response against the correct event type and id , providing a success message with the current available quantity given that the status value is true.

---

Back To Top

ms_iap_QueryEntitledProducts

This function provides the store product information for all add-ons, dlc, and consumables related to the current game that the user has an entitlement to. This is an asynchronous function that will trigger the Async In-App Purchase event when it is finished.

Syntax:

ms_iap_QueryEntitledProducts(user_id, product_kinds);

Argument	Type	Description
user_id	pointer	The user ID to use in the store context.
product_kinds	constant	The types of products to return. For more information read the Product Kinds section.

Returns:

Real (In-App Purchase Request ID)

Triggers:

Asynchronous In-App Purchase Event

Key	Type	Description
type	string	The constant "ms_iap_QueryEntitledProducts_result"
id	pointer	The asynchronous request ID.
status	bool	Whether or not the asynchronous request succeeded.
results	array	An array of Product Details structs.

Example:

var _userId = xboxone_get_activating_user();
var _product_kinds = e_ms_iap_ProductKind_Durable;

requestId = ms_iap_QueryEntitledProducts(_userId, _product_kinds);

In the code above first we get the user ID (_userId) of the activating user, afterwards we create a filter for durable products (_product_kinds) and we call the function with both arguments. The function call will then return a request ID (requestId) that can be used inside an Async In-App Purchase event.

if (async_load[? "type"] == "ms_iap_QueryEntitledProducts_result")
{
    if (async_load[? "id"] == requestId)
    {
        if (async_load[? "status"])
        {
            show_debug_message(async_load[? "result"]);
        }
    }
}

The code above matches the response against the correct event type and id , printing to the debug console the result of the query; an array of Product Details structs.

---

Back To Top

ms_iap_QueryGameLicense

This function retrieves information about the license that was acquired to allow the app to launch. This is an asynchronous function that will trigger the Async In-App Purchase event when it is finished.

Syntax:

ms_iap_QueryGameLicense(user_id);

Argument	Type	Description
user_id	pointer	The user ID to use in the store context.

Returns:

Real (In-App Purchase Request ID)

Triggers:

Asynchronous In-App Purchase Event

Key	Type	Description
type	string	The constant "ms_iap_QueryGameLicense_result"
id	pointer	The asynchronous request ID.
status	bool	Whether or not the asynchronous request succeeded.
expirationDate	real	Expiration date of the license.
isActive	bool	Indicates whether the license is active.
isTrial	bool	Indicates whether the license is a trial license.
isTrialOwnedByTheUser	bool	Indicates whether the trial is owned by the associated user. If on PC, this will be the currently signed in user to the Windows Store App.
isDiscLicense	bool	Indicates whether the license is a disc license.
skuStoreId	string	The store ID.
trialUniqueId	string	The unique ID for the trial.
trialTimeRemainingInSeconds	real	Amount of time remaining for the trial license.

Example:

var _userId = xboxone_get_activating_user();

requestId = ms_iap_QueryGameLicense(_userId);

In the code above first we get the user ID (_userId) of the activating user and we call the function with it. The function call will then return a request ID (requestId) that can be used inside an Async In-App Purchase event.

if (async_load[? "type"] == "ms_iap_QueryGameLicense_result")
{
    if (async_load[? "id"] == requestId)
    {
        if (async_load[? "status"])
        {
            show_debug_message(async_load[? "skuStoreId"]);
        }
    }
}

The code above matches the response against the correct event type and id , printing to the debug console the skuStoreId of the current game license.

---

Back To Top

ms_iap_QueryProductForCurrentGame

This function provides store product information for the currently running game, such as its SKUs, availabilities and other metadata. This is an asynchronous function that will trigger the Async In-App Purchase event when it is finished.

Syntax:

ms_iap_QueryProductForCurrentGame(user_id);

Argument	Type	Description
user_id	pointer	The user ID to use in the store context.

Returns:

Real (In-App Purchase Request ID)

Triggers:

Asynchronous In-App Purchase Event

Key	Type	Description
type	string	The constant "ms_iap_QueryProductForCurrentGame_result"
id	real	The asynchronous request ID.
status	bool	Whether or not the asynchronous request succeeded.
results	array	An array of Product Details structs.

Example:

var _userId = xboxone_get_activating_user();

requestId = ms_iap_QueryProductForCurrentGame(_userId);

In the code above first we get the user ID (_userId) of the activating user and we call the function with it. The function call will then return a request ID (requestId) that can be used inside an Async In-App Purchase event.

if (async_load[? "type"] == "ms_iap_QueryProductForCurrentGame_result")
{
    if (async_load[? "async_id"] == requestId)
    {
        if (async_load[? "status"])
        {
            show_debug_message(async_load[? "result"]);
        }
    }
}

The code above matches the response against the correct event type and id , printing to the debug console the result of the query; an array of Product Details structs.

---

Back To Top

ms_iap_QueryProductForPackage

This function retrieves store product information for the specified package. This is an asynchronous function that will trigger the Async In-App Purchase event when it is finished.

Syntax:

ms_iap_QueryProductForPackage(user_id, store_id, product_kinds);

Argument	Type	Description
user_id	pointer	The user ID to use in the store context.
store_id	string	A string that uniquely identifies a store package.
product_kinds	constant	The type of products to find. For more information read the Product Kinds section.

Returns:

Real (In-App Purchase Request ID)

Triggers:

Asynchronous In-App Purchase Event

Key	Type	Description
type	string	The constant "ms_iap_QueryProductForPackage_result"
id	real	The asynchronous request ID.
status	bool	Whether or not the asynchronous request succeeded.
results	array	An array of Product Details structs.

Example:

var _userId = xboxone_get_activating_user();
var _packageId = "XXXXXXXXXXX";
var _product_kinds = e_ms_iap_ProductKind_Consumable;

requestId = ms_iap_QueryProductForPackage(_userId, _packageId, _product_kinds);

In the code above first we get the user ID (_userId) of the activating user, we reference the package ID (_packageId) of the target game and afterwards we create a filter for consumable products (_product_kinds) finally we call the function with all those arguments. The function call will then return a request ID (requestId) that can be used inside an Async In-App Purchase event.

if (async_load[? "type"] == "ms_iap_QueryProductForPackage_result")
{
    if (async_load[? "id"] == requestId)
    {
        if (async_load[? "status"])
        {
            show_debug_message(async_load[? "result"]);
        }
    }
}

The code above matches the response against the correct event type and id , printing to the debug console the result of the query; an array of Product Details structs.

---

Back To Top

ms_iap_QueryProducts

Returns listing information for the specified products that are associated with the current game, regardless of whether the products are currently available for purchase within the current game. This is an asynchronous function that will trigger the Async In-App Purchase event when it is finished.

Syntax:

ms_iap_QueryProducts(user_id, product_kinds, store_ids, action_filters);

Argument	Type	Description
user_id	pointer	The user ID to use in the store context.
product_kinds	constant	The types of products to return. For more information read the Product Kinds section.
store_ids	string[]	Restricts the results to the given product IDs.
action_filters	string[]	Restricts the results by some action stored in the product document. By default, this API returns all products, even if they are not purchasable, but you can restrict this to "Purchase" if you only want purchasable, or "License" if you only want licensable. Other action filters include "Fulfill" , "Browse" , "Curate" , "Details" , and "Redeem" .

Returns:

Real (In-App Purchase Request ID)

Triggers:

Asynchronous In-App Purchase Event

Key	Type	Description
type	string	The constant "ms_iap_QueryProducts_result"
id	real	The asynchronous request ID.
status	bool	Whether or not the asynchronous request succeeded.
results	array	An array of Product Details structs.

Example:

var _userId = xboxone_get_activating_user();
var _product_kinds = e_ms_iap_ProductKind_Consumable;
var _action_filter = ["Purchase"];

requestId = ms_iap_QueryProducts(_userId, _product_kinds, 0, _action_filter );

In the code above first we get the user ID (_userId) of the activating user, afterwards we create a filter for consumable products (_product_kinds) and finally we call the function with all those arguments providing no store ID filter but selecting only products that are available for purchase. The function call will then return a request ID (requestId) that can be used inside an Async In-App Purchase event.

if (async_load[? "type"] == "ms_iap_QueryProducts_result")
{
    if (async_load[? "id"] == requestId)
    {
        if (async_load[? "status"])
        {
            show_debug_message(async_load[? "result"]);
        }
    }
}

The code above matches the response against the correct event type and id , printing to the debug console the result of the query; an array of Product Details structs.

---

Back To Top

ms_iap_ReleaseLicenseForDurables

This function will release a package license assigned to this console and it is intended to be be used with products of type Durable . For Durable with package type, use ms_iap_ReleaseLicenseForPackage instead.

Syntax:

ms_iap_ReleaseLicenseForDurables(store_id);

Argument	Type	Description
store_id	string	The store ID of the product.

Returns:

Real (-1 if there was an error, otherwise 0)

Example:

var _storeId = global.products[0].storeId;

var _error = ms_iap_ReleaseLicenseForDurables(_storeId);

if (_error != 0)
{
    show_debug_message("There was an error trying to release the license");
}

In the code above first we get the product ID (_storeId) conveniently stored inside a global array and call the function with this value. The returned value (_error) is then checked to see if the function was successful or not.

---

Back To Top

ms_iap_ReleaseLicenseForPackage

This function will release a package license assigned to this console and it is intended to be be used with products of type Durable with package . For Durable type, use ms_iap_ReleaseLicenseForDurables instead.

Syntax:

ms_iap_ReleaseLicenseForPackage(package_id);

Argument	Type	Description
package_id	string	The store ID of the product.

Returns:

Real (-1 if there was an error, otherwise 0)

Example:

var _packageId = global.packages[0].packageId;

var _error = ms_iap_ReleaseLicenseForPackage(_packageId);

if (_error != 0)
{
    show_debug_message("There was an error trying to release the license for the package!");
}

In the code above first we get the package ID (_packageId) conveniently stored inside a global array and call the function with this value. The returned value (_error) is then checked to see if the function was successful or not.

---

Back To Top

ms_iap_ReportConsumableFulfillment

Consumes the specified quantity of a consumable. See Consumable based ecosystems for more information on implementing and using consumable products. This is an asynchronous function that will trigger the Asynchronous In-App Purchase Event when it is finished.

Syntax:

ms_iap_ReportConsumableFulfillment(user_id, store_id, quantity, tracking_id);

Argument	Type	Description
user_id	pointer	The user ID to use in the store context.
store_id	string	The Store ID of the consumable add-on that you want to report as fulfilled.
quantity	integer	The number of units of the consumable add-on that you want to report as fulfilled. For a Store-managed consumable (that is, a consumable where Microsoft keeps track of the balance), specify the number of units that have been consumed. For a game-managed consumable (that is, a consumable where the developer keeps track of the balance), specify 1.
tracking_id	string	A developer-supplied GUID that identifies the specific transaction that the fulfillment operation is associated with for tracking purposes.

Returns:

Real (In-App Purchase Request ID)

Triggers:

Asynchronous In-App Purchase Event

Key	Type	Description
type	string	The constant "ms_iap_ReportConsumableFulfillment_result"
id	real	The asynchronous request ID.
status	bool	Whether or not the asynchronous request succeeded.
store_id	string	The store ID of the product.
consumed_quantity	integer	The amount of product that was consumed.
available_quantity	integer	The amount of product that still remains in the user's possession.

Example:

var _userId = xboxone_get_activating_user();
var _storeId = global.products[0].storeId;
var _trackingId = guid_generate(); // This function generates a unique identifier for tracking purposes.

requestId = ms_iap_ReportConsumableFulfillment(_userId, _storeId, 10, _trackingId);

In the code above first we get the user ID (_userId) of the activating user and we get the store ID (_storeId) of the product we want to report as consumed (note that for convenience we keep the products stored in a global variable) and finally we generate a tracking ID (_trackingId) required to perform the request. The function call will then return a request ID (requestId) that can be used inside an Async In-App Purchase event.

if (async_load[? "type"] == "ms_iap_ReportConsumableFulfillment_result")
{
    if (async_load[? "id"] == requestId)
    {
        if (async_load[? "status"])
        {
            show_debug_message("We consumed: " + string(async_load[? "consumed_quantity"]));
            show_debug_message("We still have: " + string(async_load[? "available_quantity"]));
        }
    }
}

The code above matches the response against the correct event type and async_id , printing to the debug console the current consumed and available quantities; upon a successful task.

---

Back To Top

ms_iap_ShowAssociatedProductsUI

This function will open up the Microsoft Store App and show the set of available add-ons associated with the game. This can be further filtered by product type.

Syntax:

ms_iap_ShowAssociatedProductsUI(user_id, store_id, product_kinds);

Argument	Type	Description
user_id	pointer	The user ID to use in the store context.
store_id	string	The store ID of the product.
product_kinds	constant	The type of products to show. For more information read the Product Kinds section.

Returns:

N/A

Example:

var _userId = xboxone_get_activating_user();
var _storeId = global.gameStoreId;
var _product_kinds = e_ms_iap_ProductKind_Consumable;

ms_iap_ShowAssociatedProductsUI(_userId, _storeId, _product_kinds);

In the code above first we get the user ID (_userId) of the activating user, we reference the store ID (_storeId) of current game (stored inside a global variable) and afterwards we create a filter for consumable products (_product_kinds) finally we call the function with all those arguments. The function call will show up the Microsoft Store App overlay with the associated consumable products.

---

Back To Top

ms_iap_ShowProductPageUI

This function will open up the Store app directly to the Product Details Page (PDP) of the provided product. This allows titles that have not integrated with the purchase flow or an in-game store UI to still drive users to products related to their title and the purchase flow found on the Product Details Page.

Syntax:

ms_iap_ShowProductPageUI(user_id, store_id);

Argument	Type	Description
user_id	pointer	The user ID to use in the store context.
store_id	string	The store ID of the product.

Returns:

N/A

Example:

var _userId = xboxone_get_activating_user();
var _storeId = global.products[0].storeId;

ms_iap_ShowProductPageUI(_userId, _storeId);

In the code above first we get the user ID (_userId) of the activating user, we reference the store ID (_storeId) of product we want to check and finally we call the function with both arguments. The function call will show up the Microsoft Store App overlay directly on the Product Details Page (PDP) of the provided Product ID.

---

Back To Top

ms_iap_ShowPurchaseUI

This function begins the purchase UI overlay for the specified product.

Syntax:

ms_iap_ShowPurchaseUI(user_id, store_id, name, json);

Argument	Type	Description
user_id	pointer	The user ID to use in the store context.
store_id	string	The store ID of the product.
name	string	Name of the product to purchase.
json	string	A JSON blob (JSON formatted string) that is handed to the purchase flow. Allows for insertion of custom campaign IDs, so you can track how the purchase started.

Returns:

N/A

Example:

var _userId = xboxone_get_activating_user();
var _storeId = global.products[0].storeId;

ms_iap_ShowPurchaseUI(_userId, _storeId, undefined, undefined);

In the code above first we get the user ID (_userId) of the activating user, we reference the store ID (_storeId) of product we want to purchase and finally we call the function with both arguments (providing no name/json, they are not demanding). The function call will show up the purchase UI overlay for the specified product.

---

Back To Top

ms_iap_ShowRateAndReviewUI

Displays a system dialog to pop up to allow the user to provide a review for the current game or decline to do so. Note: If the system detects a game is calling this excessively, it will hide the dialog.

Syntax:

ms_iap_ShowRateAndReviewUI(user_id);

Argument	Type	Description
user_id	pointer	The user ID to use in the store context.

Returns:

N/A

Example:

var _userId = xboxone_get_activating_user();

ms_iap_ShowRateAndReviewUI(_userId);

In the code above first we get the user ID (_userId) of the activating user and finally we call the function with it's value. The function call will show a system dialog pop up to allow the user to provide a review for the current game.

---

Back To Top

ms_iap_ShowRedeemTokenUI

This function triggers a token redemption for a given user and specified token.

Syntax:

ms_iap_ShowRedeemTokenUI(user_id, token, allowed_store_ids, disallow_cvs_redemption);

Argument	Type	Description
user_id	pointer	The user ID to use in the store context.
token	string	The token to redeem. This value cannot be undefined, if you want to bring up the UI without providing a code to pre-populate in the UI pass in a single space .
allowed_store_ids	string[]	An array of product store IDs. This allows you to restrict the 5x5 codes to only work with specific products.
disallow_cvs_redemption	bool	Prevents CSV (giftcard/money style 5x5s) from being redeemed.

Returns:

N/A

Example:

var _userId = xboxone_get_activating_user();
var _token = global.finalWeaponToken;

ms_iap_ShowRateAndReviewUI(_userId, _token, undefined, false);

In the code above first we get the user ID (_userId) of the activating user and reference a token to be redeemed (_token), finally we call the function with those values, applying no restrictions whatsoever. The function call will triggers a token redemption for a given user and specified token.

---

Back To Top

ms_iap_UnmountPackage

This function unmounts the installation of specified content. This is an asynchronous function that will trigger the Async In-App Purchase event when it is finished.

Syntax:

ms_iap_UnmountPackage(package_id);

Argument	Type	Description
package_id	string	A string that uniquely identifies the installed package on the disk. Pass in the packageIdentifier field from the Package Details struct returned from the ms_iap_EnumeratePackages async callback.

Returns:

Real (In-App Purchase Request ID)

Triggers:

Asynchronous In-App Purchase Event

Key	Type	Description
type	string	The string value "ms_iap_UnmountPackage_result".
id	real	The asynchronous request ID.
package_id	string	A string that uniquely identifies the installed package on the disk.
mount_path	string	The path to the unmounted installation.

Example:

var _package = global.package[0].packageId;

requestId = ms_iap_UnmountPackage(_package);

In the code above first we get the user ID (_userId) of the activating user and after that we execute the function passing in an array of packages to be downloaded and installed. The function call will then return a request ID (requestId) that can be used inside an Async In-App Purchase event.

if (async_load[? "type"] == "ms_iap_UnmountPackage_result")
{
    if (async_load[? "id"] == requestId)
    {
        show_debug_message("Package ID: " + async_load[? "package_id"]);
        show_debug_message("Finished unmount!");
    }
}

The code above matches the response against the correct event type and id , printing to the debug console the current packages ID and a success message.

---

Back To Top

Addon License Details

This struct is returned as an async result of the call to ms_iap_QueryAddOnLicenses and it contains details about an add-on license.

Property	Type	Description
skuStoreId	string	The SKU ID for the license.
isActive	bool	Indicates if the license is active.
expirationDate	real	Expiration date of the license ( -1 , if the license doesn't expire)
inAppOfferToken	string	The title defined offer token that you can use to map items internally. For example: "com.company.product.itemname" .

The entity described above is a struct meaning it's properties can be accessed using the dot operator much like when accessing instance variables, for example:

var _addonLicenseDetails = global.addonLicenses[0];

show_debug_message(_packageDetails.packageIdentifier);
show_debug_message(_packageDetails.version);

The code above will grab a package detail struct from a global variable (where they were previously store for this sample) and we are accessing the packageIdentifier and version properties of that struct.

---

Back To Top

Package Details

This struct is returned as an async result of the call to ms_iap_EnumeratePackages and it contains details about an installation.

Property	Type	Description
packageIdentifier	string	A string that uniquely identifies the installed package on the disk.
version	string	A store managed consumable product.
kind	constant	The value that indicates whether the package is an app package or a content package (see Package Kinds)
displayName	string	The display name.
description	string	The description of the package.
publisher	string	The publisher of the package.
storeId	string	The unique ID of the product.
installing	bool	The bool that indicates whether the package is currently installing.

The entity described above is a struct meaning it's properties can be accessed using the dot operator much like when accessing instance variables, for example:

var _packageDetails = global.packageDetails[0];

show_debug_message(_packageDetails.packageIdentifier);
show_debug_message(_packageDetails.version);

The code above will grab a package detail struct from a global variable (where they were previously store for this sample) and we are accessing the packageIdentifier and version properties of that struct.

---

Back To Top

Product Details

This struct is returned as an async result of the call to the following API function calls:

• ms_iap_QueryAssociatedProducts

• ms_iap_QueryEntitledProducts

• ms_iap_QueryProductForCurrentGame

• ms_iap_QueryProductForPackage

• ms_iap_QueryProducts

  and it contains details that describe a store product.

Property	Type	Description
storeId	string	The product ID.
title	string	The title of the product.
description	string	A description of the store product.
language	string	The International Organization of Standards (ISO) identifier representing the language the title and description strings are (more details)
inAppOfferToken	string	Game defined offer token that you can use to map items internally. For example: " com.company.product.itemname ".
linkUri	string	The URI to the product.
productKind	constant	Indicates the type of store product. For more information read the Product Kinds section.
price	struct	The price information for the store product (read Price below)
hasDigitalDownload	bool	Indicates whether the store product has a digital download.
isInUserCollection	bool	Indicates if the product is in the user collection.
keywords	string[]	Keywords associated with the store product.
images	array	Array of images associated with the product (read Image below)

Price

Price details inside the product struct use their own struct with data, following the schema below:

Property	Type	Description
basePrice	real	The normal non-promotional price or MSRP of the product.
price	real	The actual price that the user would pay if they purchased the item.
recurrecePrice	real	The recurrence price.
currencyCode	string	The currency code for the price.
formattedBasePrice	string	The formatted basePrice that can be shown in the game's UI.
formattedPrice	string	The formatted price that should be used in your UI to advertise the product.
formattedRecurrentPrice	string	The formatted recurrence price.
isOnSale	bool	Indicates whether the product is on sale.
saleEndData	real	The end date for the sale.

Image

Image details inside the product struct use their own array of structs with data, following the schema below:

Property	Type	Description
uri	real	The URI to the image.
height	real	The height of the image.
width	real	The width of the image.
caption	string	The caption for the image.
imagePurposeTag	string	A string containing a tag indicating the purpose of the image.

The entity described above is a struct meaning it's properties can be accessed using the dot operator much like when accessing instance variables, for example:

var _productDetails = global.productDetails[0];

show_debug_message(_productDetails.description);
show_debug_message(_productDetails.price.basePrice);

The code above will grab a product detail struct from a global variable (where they were previously store for this sample) and we are accessing the description text and basePrice (inside the price struct) **** properties of that struct.

---

Back To Top

Package Kinds

Package kind indicates the package type. They are used as a filter for the ms_iap_EnumeratePackages function to acquire information about packages of a certain type. It is also a member of the Package Details struct which describes a store product.

Constant	Description
e_ms_iap_PackageKind_Game	The installation package contains a game.
e_ms_iap_PackageKind_Content	The installation package contains downloadable content.

---

Back To Top

Package Scopes

Package scope indicates the scope of packages to be returned when installation packages are being enumerated while using the ms_iap_EnumeratePackages function call.

Constant	Description
e_ms_iap_PackageEnumerationScope_ThisOnly	Scope is limited to just apps or content associated with the calling process.
e_ms_iap_PackageEnumerationScope_ThisAndRelated	Scope includes apps or content associated with the calling process and also includes apps or content that are associated with any package the calling process has added to its RelatedProducts section of its game config file.

---

Back To Top

Products Kinds

Product kinds indicates the product type. They are used as a filter for many IAP queries to acquire information about products of a certain type. It is also a member of the Product Details struct which describes a store product. The product kind is represented as a flagged constant meaning it can be combined using the bit-wise or operator to represent multiple types of product at once.

Constant	Description
e_ms_iap_ProductKind_None	Not a product type.
e_ms_iap_ProductKind_Consumable	A store managed consumable product.
e_ms_iap_ProductKind_Durable	Durable product.
e_ms_iap_ProductKind_Game	A game.
e_ms_iap_ProductKind_Pass	A pass.
e_ms_iap_ProductKind_UnmanagedConsumable	A game managed consumable product, also known as an unmanaged consumable.

As explained above the product kinds can be combined using the bit-wise or operator following the example below:

var _consumableAndDurableType = e_ms_iap_ProductKind_Consumable | e_ms_iap_ProductKind_Durable;

The code above will make it so the _consumableAndDurableType variable will filter both consumables and durables.

---