purchase.mp.microsoft.com/v7.0/purchases/grant - XBOX Game Development Documentation

Use the Microsoft Store purchase API to grant a free app or add-on to a user’s account. Only free products can be granted directly to a user’s account. Grant attempts for paid products return an error.

Prerequisites

Review Prerequisites for service-to-service APIs. This API only supports the Microsoft Entra ID auth type. If product configuration isn’t published in Partner Center, can succeed but return no results.

Request

Request syntax

Method	Request URI
`POST`	`https://purchase.mp.microsoft.com/v7.0/purchases/grant`

Request header

Header	Type	Description
`Authorization`	`string`	Required. The Microsoft Entra ID service access token in the form `Bearer` <token>.
`Host`	`string`	Must be set to the value `purchase.mp.microsoft.com`.
`Content-Length`	`number`	The length of the request body.
`Content-Type`	`string`	Specifies the request and response type. Currently, the only supported value is `application/json`.

Request body

Parameter	Type	Description	Required
`availabilityId`	`string`	The availability ID of the product to be granted from the Microsoft Store catalog.	Yes
`b2bKey`	`string`	The User Store ID key that represents the identity of the user for whom you want to grant a product.	Yes
`devOfferId`	`string`	A developer-specified offer ID that appears in the Collection item after purchase.	No
`language`	`string`	The language of the user.	Yes
`market`	`string`	The market of the user.	Yes
`orderId`	`GUID`	A GUID generated for the order. This value is unique for the user, but it isn’t required to be unique across all orders.	Yes
`productId`	`string`	The Store ID for the product in the Microsoft Store catalog. An example Store ID for a product is 9NBLGGH42CFD.	Yes
`quantity`	`int`	The quantity to purchase. Currently, the only supported value is 1. If not specified, the default is 1.	No
`skuId`	`string`	The Store ID for the product’s SKU in the Microsoft Store catalog. An example Store ID for a SKU is 0010.	Yes
`sbx`	`string`	Optional value for authenticating with UserStoreIds that specifies the Sandbox the results should be scoped to. Default without this value is the RETAIL sandbox. X-Token auth doesn’t need this value as the Sandbox is specified within the X-Token.	No

Request example

POST https://purchase.mp.microsoft.com/v7.0/purchases/grant HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJK...
Content-Length: 1863
Content-Type: application/json

{
    "b2bKey" : "eyJ0eXAiOiJK...",
    "availabilityId" : "9RT7C09D5J3W",
    "productId" : "9NBLGGH5WVP6",
    "skuId" : "0010",
    "language" : "en-us",
    "market" : "us",
    "orderId" : "3eea1529-611e-4aee-915c-345494e4ee76",
    "sbx" : "XDKS.1"
}

Response

Response body

Parameter	Type	Description	Required
`clientContext`	`ClientContextV8`	The client contextual information for the order. Assigned to the `clientID` value from the Microsoft Entra ID token.	Yes
`createdtime`	`datetimeoffset`	The time that the order was created.	Yes
`currencyCode`	`string`	The currency code for `totalAmount` and `totalTaxAmount`. N/A for free items.	Yes
`friendlyName`	`string`	The friendly name for the order. N/A for orders made by using the Microsoft Store purchase API.	Yes
`isPIRequired`	`boolean`	Indicates whether a payment instrument (PI) is required as part of the purchase order.	Yes
`language`	`string`	The language ID for the order (for example, “en”).	Yes
`market`	`string`	The market ID for the order (for example, “US”).	Yes
`orderId`	`string`	An ID that identifies the order for a particular user.	Yes
`orderLineItems`	`list<OrderLineItemV8>`	The list of line items for the order. Typically, there’s one line item per order.	Yes
`orderState`	`string`	The state of the order. The valid states are `Editing`, `CheckingOut`, `Pending`, `Purchased`, `Refunded`, `ChargedBack`, and `Canceled`.	Yes
`orderValidityEndTime`	`string`	When the order pricing ends, N/A for free apps.	Yes
`orderValidityStartTime`	`string`	When the order pricing starts, N/A for free apps.	Yes
`purchaser`	`IdentityV6`	An object that describes the identity of the purchaser.	Yes
`totalAmount`	`decimal`	The total purchase amount of all items in the order including tax.	Yes
`totalAmountBeforeTax`	`decimal`	The total purchase amount of all items in the order before tax.	Yes
`totalChargedToCsvTopOffPI`	`decimal`	If using a separate payment instrument and stored value (comma-separated value (CSV)), the amount charged to CSV.	Yes
`totalTaxAmount`	`decimal`	The total amount of tax for all line items.	Yes

The ClientContext object contains the following parameters.

Parameter	Type	Description	Required
`client`	`string`	The client ID that created the order.	No

The OrderLineItemV8 object contains the following parameters.

Parameter	Type	Description	Required
`agent`	`IdentityV8`	The agent that last edited the line item. For more information about this object, see the following table.	No
`availabilityId`	`string`	The availability ID of the product to be purchased from the Microsoft Store catalog.	Yes
`beneficiary`	`IdentityV8`	The identity of the beneficiary of the order.	No
`billingState`	`string`	The billing state of the order. Set to `Charged` when completed.	No
`campaignId`	`string`	The campaign ID for this order.	No
`currencyCode`	`string`	The currency code that’s used for price details.	Yes
`description`	`string`	A localized description of the line item.	Yes
`devofferId`	`string`	The offer ID for the particular order, if present.	No
`fulfillmentDate`	`datetimeoffset`	The date that the fulfillment occurred.	No
`fulfillmentState`	`string`	The state of the item’s fulfillment. Set to `Fulfilled` when completed.	No
`isPIRequired`	`boolean`	Indicates whether a payment instrument is required for this line item.	Yes
`isTaxIncluded`	`boolean`	Indicated whether tax is included in the pricing details of the item.	Yes
`legacyBillingOrderId`	`string`	The legacy billing ID.	No
`lineItemId`	`string`	The line item ID for the item in this order.	Yes
`listPrice`	`decimal`	The list price of the item in this order.	Yes
`productId`	`string`	The Store ID for the product that represents the line item in the Microsoft Store catalog. An example Store ID for a product is 9NBLGGH42CFD.	Yes
`productType`	`string`	The type of the product. The supported values are `Durable`, `Application`, and `UnmanagedConsumable`.	Yes
`quantity`	`int`	The quantity of the item ordered.	Yes
`retailPrice`	`decimal`	The retail price of the item ordered.	Yes
`revenueRecognitionState`	`string`	The revenue recognition state.	Yes
`skuId`	`string`	The Store ID for the SKU of the line item in the Microsoft Store catalog. An example Store ID for a SKU is 0010.	Yes
`taxAmount`	`decimal`	The tax amount for the line item.	Yes
`taxType`	`string`	The tax type for the applicable taxes.	Yes
`Title`	`string`	The localized title of the line item.	Yes
`totalAmount`	`decimal`	The total purchase amount of the line item including tax.	Yes

The IdentityV8 object contains the following parameters.

Parameter	Type	Description	Required
`identityType`	`string`	Contains the value `"pub"`.	Yes
`identityValue`	`string`	The string value of the publisherUserId from the specified User Store ID key.	Yes

Response example

Content-Length: 1203
Content-Type: application/json
MS-CorrelationId: fb2e69bc-f26a-4aab-a823-7586c19f5762
MS-RequestId: c1bc832c-f742-47e4-a76c-cf061402f698
MS-CV: XfrNWLQlEaux6Mt.8
MS-ServerId: 030032362
Date: Tue, 13 Oct 2019 21:21:51 GMT

{
    "clientContext": {
        "client": "86b78998-d05a-487b-b380-6c738f6553ea"
    },
    "createdTime": "2015-10-13T21:21:51.1863494+00:00",
    "currencyCode": "USD",
    "isPIRequired": false,
    "language": "en-us",
    "market": "us",
    "orderId": "3eea1529-611e-4aee-915c-345494e4ee76",
    "orderLineItems": [{
        "availabilityId": "9RT7C09D5J3W",
        "beneficiary": {
            "identityType": "pub",
            "identityValue": "user1"
        },
        "billingState": "Charged",
        "currencyCode": "USD",
        "description": "Jewels, Jewels, Jewels - Consumable 2",
        "fulfillmentDate": "2015-10-13T21:21:51.639478+00:00",
        "fulfillmentState": "Fulfilled",
        "isPIRequired": false,
        "isTaxIncluded": true,
        "lineItemId": "2814d758-3ee3-46b3-9671-4fb3bdae9ffe",
        "listPrice": 0.0,
        "payments": [],
        "productId": "9NBLGGH5WVP6",
        "productType": "UnmanagedConsumable",
        "quantity": 1,
        "retailPrice": 0.0,
        "revenueRecognitionState": "None",
        "skuId": "0010",
        "taxAmount": 0.0,
        "taxType": "NoApplicableTaxes",
        "title": "Jewels, Jewels, Jewels - Consumable 2",
        "totalAmount": 0.0
    }],
    "orderState": "Purchased",
    "orderValidityEndTime": "2015-10-14T21:21:51.1863494+00:00",
    "orderValidityStartTime": "2015-10-13T21:21:51.1863494+00:00",
    "purchaser": {
        "identityType": "pub",
        "identityValue": "user1"
    },
    "testScenarios": "None",
    "totalAmount": 0.0,
    "totalTaxAmount": 0.0
}

Error codes

Code	Error	Inner error code	Description
401	Unauthorized	AuthenticationTokenInvalid	The Microsoft Entra ID access token is invalid. In some cases, the ServiceError details contain more information, such as when the token is expired or the appid claim is missing.
401	Unauthorized	PartnerAadTicketRequired	A Microsoft Entra ID access token wasn’t passed to the service in the authorization header.
401	Unauthorized	InconsistentClientId	The `clientId` claim in the User Store ID key and the `appid` in the Access token don’t match.
400	BadRequest	InvalidParameter	The details contain information regarding the request body and which fields have an invalid value.

Manage products from your services Requesting a User Store ID for service-to-service authentication Renew a Microsoft Store ID key

​Prerequisites

​Request

​Request syntax

​Request header

​Request body

​Request example

​Response

​Response body

​Response example

​Error codes

​Related articles