iap

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:

• PackageKind
• PackageScope
• ProductKind

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:

• AddonLicenseDetails
• PackageDetails
• ProductDetails
• Price

---

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 function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the In-App Purchase Async Event.

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:

In-App Purchase Async Event

Key	Type	Description
type	String	The constant "ms_iap_AcquireLicenseForDurables_result"
id	Real	The asynchronous request ID.
status	Boolean	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 In-App Purchase Async 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 function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the In-App Purchase Async Event.

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:

In-App Purchase Async Event

Key	Type	Description
type	String	The constant "ms_iap_AcquireLicenseForPackage_result"
id	Real	The asynchronous request ID.
status	Boolean	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 In-App Purchase Async 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 function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the In-App Purchase Async Event.

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:

In-App Purchase Async Event

Key	Type	Description
type	String	The string value "ms_iap_CanAcquireLicenseForPackage_result".
async_id	Real	The asynchronous request ID.
async_status	Boolean	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	Real	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 In-App Purchase Async 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 function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the In-App Purchase Async Event.

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:

In-App Purchase Async Event

Key	Type	Description
type	String	The string value "ms_iap_CanAcquireLicenseForStoreId_result".
async_id	Real	The asynchronous request ID.
async_status	Boolean	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	Real	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 In-App Purchase Async 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.

The async completion message will only be raised when the package is actually installed (not just registered).

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the In-App Purchase Async Event.

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	Array of String	An array of strings that uniquely identify the store packages.

Returns:

Real

(In-App Purchase Request ID)

Triggers:

In-App Purchase Async Event

Key	Type	Description
type	String	The string value "ms_iap_DownloadAndInstallPackages_result".
id	Real	The asynchronous request ID.
status	Boolean	Whether or not the asynchronous request succeeded.
package_ids	Array of 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 In-App Purchase Async 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 with all the installed package IDs.

---

Back To Top

ms_iap_EnumeratePackages

This function enumerates the results of a package query.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the In-App Purchase Async Event.

Syntax:

ms_iap_EnumeratePackages(package_kind, scope)

Argument	Type	Description
package_kind	PackageKind	The value that indicates whether to enumerate app packages or content packages
scope	PackageScope	The scope of the installation packages

Returns:

Real

(In-App Purchase Request ID)

Triggers:

In-App Purchase Async Event

Key	Type	Description
type	String	The string value "ms_iap_EnumeratePackages_result".
id	Real	The asynchronous request ID.
status	Boolean	Whether or not the asynchronous request succeeded.
results	Array of PackageDetails	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 of 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 In-App Purchase Async 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 with all the PackageDetails structs.

---

Back To Top

ms_iap_MountPackage

This function mounts the installation of specified content.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the In-App Purchase Async Event.

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 PackageDetails struct returned from the ms_iap_EnumeratePackages async callback.

Returns:

Real

(In-App Purchase Request ID)

Triggers:

In-App Purchase Async 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 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 In-App Purchase Async 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 package's ID and its 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 function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the In-App Purchase Async Event.

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:

In-App Purchase Async Event

Key	Type	Description
type	String	The constant "ms_iap_QueryAddOnLicenses_result"
id	Real	The asynchronous request ID.
status	Boolean	Whether or not the asynchronous request succeeded.
result	Array of AddonLicenseDetails	An array of AddonLicenseDetails 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 In-App Purchase Async 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 AddonLicenseDetails 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 function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the In-App Purchase Async Event.

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	ProductKind	The types of product to return. For more information read the ProductKind section.

Returns:

Real

(In-App Purchase Request ID)

Triggers:

In-App Purchase Async Event

Key	Type	Description
type	String	The constant "ms_iap_AcquireLicenseForDurables_result"
id	Real	The asynchronous request ID.
status	Boolean	Whether or not the asynchronous request succeeded.
results	Array of ProductDetails	An array of ProductDetails 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 In-App Purchase Async 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 function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the In-App Purchase Async Event.

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:

In-App Purchase Async Event

Key	Type	Description
type	String	The constant "ms_iap_QueryConsumableBalanceRemaining_result"
id	Real	The asynchronous request ID.
status	Boolean	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 In-App Purchase Async 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 function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the In-App Purchase Async Event.

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	ProductKind	The types of product to return.

Returns:

Real

(In-App Purchase Request ID)

Triggers:

In-App Purchase Async Event

Key	Type	Description
type	String	The constant "ms_iap_QueryEntitledProducts_result"
id	Pointer	The asynchronous request ID.
status	Boolean	Whether or not the asynchronous request succeeded.
results	Array of ProductDetails	An array of ProductDetails 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 In-App Purchase Async 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 ProductDetails structs.

---

Back To Top

ms_iap_QueryGameLicense

This function retrieves information about the license that was acquired to allow the app to launch.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the In-App Purchase Async Event.

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:

In-App Purchase Async Event

Key	Type	Description
type	String	The constant "ms_iap_QueryGameLicense_result"
id	Pointer	The asynchronous request ID.
status	Boolean	Whether or not the asynchronous request succeeded.
expirationDate	Real	Expiration date of the license.
isActive	Boolean	Indicates whether the license is active.
isTrial	Boolean	Indicates whether the license is a trial license.
isTrialOwnedByTheUser	Boolean	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	Boolean	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 we first 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 In-App Purchase Async 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 function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the In-App Purchase Async Event.

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:

In-App Purchase Async Event

Key	Type	Description
type	String	The constant "ms_iap_QueryProductForCurrentGame_result"
id	Real	The asynchronous request ID.
status	Boolean	Whether or not the asynchronous request succeeded.
results	Array of ProductDetails	An array of ProductDetails 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 In-App Purchase Async 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 ProductDetails structs.

---

Back To Top

ms_iap_QueryProductForPackage

This function retrieves store product information for the specified package.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the In-App Purchase Async Event.

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	ProductKind	The types of product to find.

Returns:

Real

(In-App Purchase Request ID)

Triggers:

In-App Purchase Async Event

Key	Type	Description
type	String	The constant "ms_iap_QueryProductForPackage_result"
id	Real	The asynchronous request ID.
status	Boolean	Whether or not the asynchronous request succeeded.
results	Array of ProductDetails	An array of ProductDetails 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 In-App Purchase Async 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 ProductDetails 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 function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the In-App Purchase Async Event.

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	ProductKind	The types of product to return.
store_ids	Array of String	Restricts the results to the given product IDs.
action_filters	Array of 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:

In-App Purchase Async Event

Key	Type	Description
type	String	The constant "ms_iap_QueryProducts_result"
id	Real	The asynchronous request ID.
status	Boolean	Whether or not the asynchronous request succeeded.
results	Array of ProductDetails	An array of ProductDetails 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 we first 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 In-App Purchase Async 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 ProductDetails 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 we first 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 function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the In-App Purchase Async Event.

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	Real	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:

In-App Purchase Async Event

Key	Type	Description
type	String	The constant "ms_iap_ReportConsumableFulfillment_result"
id	Real	The asynchronous request ID.
status	Boolean	Whether or not the asynchronous request succeeded.
store_id	String	The store ID of the product.
consumed_quantity	Real	The amount of product that was consumed.
available_quantity	Real	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 we first 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 In-App Purchase Async 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	ProductKind	The types of product to show.

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 we first 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 bring 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 we first 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 bring 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 we first get the user ID (_userId) of the activating user, we reference the store ID (_storeId) of the 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 bring 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 we first 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	Array of String	An array of product store IDs. This allows you to restrict the 5x5 codes to only work with specific products.
disallow_cvs_redemption	Boolean	Prevents CVS (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 we first 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 trigger 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 function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the In-App Purchase Async Event.

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 PackageDetails struct returned from the ms_iap_EnumeratePackages async callback.

Returns:

Real

(In-App Purchase Request ID)

Triggers:

In-App Purchase Async 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 we first 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 In-App Purchase Async 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 package ID and a success message.

---

Back To Top

PackageKind

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 PackageDetails struct which describes a store product.

These constants are referenced by the following functions:

• ms_iap_EnumeratePackages

These constants are referenced by the following structs:

• PackageDetails

Member	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

PackageScope

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

These constants are referenced by the following functions:

• ms_iap_EnumeratePackages

Member	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

ProductKind

Product kinds indicate 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 ProductDetails 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.

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.

These constants are referenced by the following functions:

• ms_iap_QueryAssociatedProducts
• ms_iap_QueryEntitledProducts
• ms_iap_QueryProductForPackage
• ms_iap_QueryProducts
• ms_iap_ShowAssociatedProductsUI

These constants are referenced by the following structs:

• ProductDetails

Member	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.

---

Back To Top

AddonLicenseDetails

This struct contains details about an add-on license.

The entity described above is a struct meaning its 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.

This struct is referenced by the following functions:

• ms_iap_QueryAddOnLicenses

Member	Type	Description
skuStoreId	String	The SKU ID for the license.
isActive	Boolean	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".

---

Back To Top

PackageDetails

This struct contains details about an installation.

The entity described above is a struct meaning its 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.

This struct is referenced by the following functions:

• ms_iap_EnumeratePackages

Member	Type	Description
packageIdentifier	String	A string that uniquely identifies the installed package on the disk.
version	String	A store managed consumable product.
kind	PackageKind	The value that indicates whether the package is an app package or a content package
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	Boolean	The bool that indicates whether the package is currently installing.

---

Back To Top

ProductDetails

This struct contains details that describe a store product.

This struct is referenced by the following functions:

• ms_iap_QueryAssociatedProducts
• ms_iap_QueryEntitledProducts
• ms_iap_QueryProductForCurrentGame
• ms_iap_QueryProductForPackage
• ms_iap_QueryProducts

Member	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	ProductKind	Indicates the type of store product. For more information read the Product Kinds section.
price	Price	The price information for the store product (read Price below)
hasDigitalDownload	Boolean	Indicates whether the store product has a digital download.
isInUserCollection	Boolean	Indicates if the product is in the user collection.
keywords	String	]
images	Array	Array of images associated with the product (read Image below)

---

Back To Top

Price

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

This struct is referenced by the following structs:

• ProductDetails

Member	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	Boolean	Indicates whether the product is on sale.
saleEndData	Real	The end date for the sale.

/**

---