Store Development Entitlements Tool (DevEntitlementTool.exe)

Article
03/28/2024

Command-line tool to query, add, and remove Microsoft Store entitlements to/from Xbox test accounts in sandbox.

Usage

deventitlementtool <command> -e <testaccountemail> -s <sandboxid> [-p <productid>] [...]

Command	Description
query	Look up entitlements owned by an account
add	Add the specified entitlement(s) to account
delete	Delete the specified entitlement(s) from account
catalog	Show the available products sellable by specified parent product

All commands require the -e (email) and -s (sandbox) parameters. Initial sign-in with an account will invoke an interactive password entry dialog. Once successfully signed in, subsequent operations with the same account/sandbox on the device will no longer require password entry.

query

deventitlementtool query -e <testaccountemail> -s <sandboxid>

List all directly owned entitlements associated with this account in the sandbox.

query output

Entitlements found: {Number of entitlements}
{ProductID}: {Last Updated Date (UTC)} {Status}
...

query example

> DevEntitlementTool.exe query -e xdks-testaccount00000@xboxtest.com -s XDKS.1
Entitlements found: 2
9MT5TGW893HV: 4/18/2023 5:05:19 PM Active
9N3KNR1TDV5V: 2/5/2024 8:39:18 PM Active

add

deventitlementtool add -e <testaccountemail> -s <sandboxid> -p <productid1> [<productid2> <productid3> ...] [-q <quantity>]

Adds an entitlement for the specified product(s) to the account. This will be the equivalent of purchasing the product from Store or through purchase API.

For Game, Durable, Bundle, and Dev-Managed consumable products, if an add is attempted on already entitled product (or the quantity is 1) it will report the existing entitlement; no new entitlement or quantity is added.

For Store-managed consumable products, a default quantity of 1 is added to the consumable balance on each add command. An optional quantity value can be specified to change this default value, but the quantity field can only be used if a single productID is passed with -p. This is useful for consumables that grant a quantity greater than 1 on purchase.

Note

Quantity is not verifiable with this tool. Examine the XStoreCollectionData struct to determine quantity.

Adding a product that is a bundle will grant all of its included products. If a quantity is specified and the bundle includes Store-managed consumables, the same quantity will be assigned to each consumable.

Note

Subscription products are not supported.

add output

Entitlements added: {Number of entitlements}
{ProductID}: {Last Updated Date (UTC)} {Status}
...

add examples

Single entitlement added

> DevEntitlementTool.exe add -e xdks-test00000@xboxtest.com -s XDKS.1 -p 9MT5TGW893HV
Entitlements added: 1
9MT5TGW893HV: 2/20/2024 12:21:25 AM Active

Multiple entitlements added

> DevEntitlementTool.exe add -e xdks-test00000@xboxtest.com -s XDKS.1 -p 9P23V43P0XZZ 9N30KZZF4BR9 9NCX1H100M18 9NQWJKKNHF1L 
Entitlements added: 4
9P23V43P0XZZ: 2/20/2024 12:33:20 AM Active
9N30KZZF4BR9: 2/20/2024 12:33:20 AM Active
9NCX1H100M18: 2/20/2024 12:33:20 AM Active
9NQWJKKNHF1L: 2/20/2024 12:33:20 AM Active

Add consumable with quantity

> DevEntitlementTool.exe add -e xdks-test00000@xboxtest.com -s XDKS.1 -p 9MT5TGW893HV -q 4321
Entitlements added: 1
9MT5TGW893HV: 2/20/2024 12:34:35 AM Active

delete

deventitlementtool delete -e <testaccountemail> -s <sandboxid> -p <productid1> [<productid2> <productid3> ...] [--all]

Deletes the specified entitlement(s) from the account.

If --all is specified, it will attempt to delete all entitlements associated with the account and sandbox.

A Revoked status will show for deleting entitlements that were granted by this tool.

A Refunded status will show for deleting entitlements that were purchased conventionally through Store client or in-game API.

delete output

Entitlements deleted: {Number of entitlements}
{ProductID}: {Last Updated Date (UTC)} {Status}
...

delete examples

> DevEntitlementTool.exe delete -e xdks-test00000@xboxtest.com -s XDKS.1 -p 9P23V43P0XZZ 9N30KZZF4BR9 9NCX1H100M18
Entitlements deleted: 3
9P23V43P0XZZ: 2/20/2024 2:26:13 AM Revoked
9N30KZZF4BR9: 2/20/2024 2:26:13 AM Revoked
9NCX1H100M18: 2/20/2024 2:26:13 AM Revoked

> DevEntitlementTool.exe delete -e xdks-test00000@xboxtest.com -s XDKS.1 -p 9PLRFWZWWF91
Entitlements deleted: 1
9PLRFWZWWF91: 1/1/0001 12:00:00 AM Refunded

catalog

deventitlementtool catalog -e <testaccountemail> -s <sandboxid> -p <productid1>

deventitlementtool catalog -e testaccountemail -s sandbox -p productid

Shows the set of products sellable by the provided product ID; i.e. child add-on products and products with a can use and sell relationship to the productID in Partner Center. This command is the equivalent to what is returned by XStoreQueryAssociatedProductsAsync. Products that are configured in Partner Center as available but not discoverable in the Microsoft Store will not be returned by this command.

catalog output

{ProductID} can sell {Number of products} products:
1. {ProductID} {Product Name} ({Product Type})
2. {ProductID} {Product Name} ({Product Type})
...

catalog example

> DevEntitlementTool.exe catalog -e xdks-test00000@xboxtest.com -s XDKS.1 -p 9NTL0QDWZ4FS
9NTL0QDWZ4FS can sell 16 products:
1. 9PHPTTDP88F7: ATG Season Pass 1 (Durable)
2. 9NMDDZC7ZWRM: ATG Sample Year 1 Pass (Durable)
3. 9PGLXLWS7319: ATG Consumable Only Bundle (Durable)
4. 9P23V43P0XZZ: ATG Sample Durable 2 (Durable)
5. 9MZ0MGGFPLTP: ATG Sample Subscription 1 (Durable)
6. 9MT5TGW893HV: ATG Sample Consumable 3 (10) (Consumable)
7. 9N30KZZF4BR9: ATG Sample Durable 1 (Durable)
8. 9PLRFWZWWF91: ATG Sample Durable 4 (Durable)
9. 9PLNMXRKNM4C: ATG Sample Durable 1 (with package) (Durable)
10. 9P8S15PJTB0P: ATG Sample Durable 3 (Durable)
11. 9NCX1H100M18: ATG Sample Consumable 2 (50) (Consumable)
12. 9N0297GK108W: ATG Dev managed consumable 1 (UnmanagedConsumable)
13. 9NQWJKKNHF1L: ATG Downloadable Content Sample (Game)
14. 9NRGW2QG5PCW: ATG Sample Pre-Order 1 (Durable)
15. 9PHHWZ12RR23: ATG In-Game Store Deluxe Add-on (Durable)
16. 9PFL4RQTB1P6: ATG Sample Consumable 1 (1) (Consumable)

Remarks

This tool is strictly for use with Xbox test accounts and for sandbox products. Use for retail accounts and scenarios is blocked.

There is a limit of add and delete operations per account per day. This will be adjusted based on observed usage. Please reach out to your Microsoft Account Representative to make requests for increasing limits.

Share via