Query for products
Use this method in the Microsoft Store collection API to get all the products that a customer owns for apps that are associated with your Azure AD client ID. You can scope your query to a particular product, or use other filters.
This method is designed to be called by your service in response to a message from your app. Your service should not regularly poll for all users on a schedule.
The Microsoft.StoreServices library provides the functionality of this method through the StoreServicesClient.CollectionsQueryAsync API.
Prerequisites
To use this method, you will need:
- An Azure AD access token that has the audience URI value
https://onestore.microsoft.com. - A Microsoft Store ID key that represents the identity of the user whose products you want to get.
For more information, see Manage product entitlements from a service.
Request
Request syntax
| Method | Request URI |
|---|---|
| POST | https://collections.mp.microsoft.com/v6.0/collections/query |
Request header
| Header | Type | Description |
|---|---|---|
| Authorization | string | Required. The Azure AD access token in the form Bearer <token>. |
| Host | string | Must be set to the value collections.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 |
|---|---|---|---|
| beneficiaries | list<UserIdentity> | A list of UserIdentity objects that represent the users being queried for products. For more information, see the table below. | Yes |
| continuationToken | string | If there are multiple sets of products, the response body returns a continuation token when the page limit is reached. Provide that continuation token here in subsequent calls to retrieve remaining products. | No |
| maxPageSize | number | The maximum number of products to return in one response. The default and maximum value is 100. | No |
| modifiedAfter | datetime | If specified, the service only returns products that have been modified after this date. | No |
| parentProductId | string | If specified, the service only returns add-ons that correspond to the specified app. | No |
| productSkuIds | list<ProductSkuId> | If specified, the service only returns products applicable to the provided product/SKU pairs. For more information, see the table below. | No |
| productTypes | list<string> | Specifies which products types to return in the query results. Supported product types are Application, Durable, Game, and UnmanagedConsumable. | Yes |
| validityType | string | When set to All, all products for a user will be returned, including expired items. When set to Valid, only products that are valid at this point in time are returned (that is, they have an active status, start date < now, and end date is > now). | No |
The UserIdentity object contains the following parameters.
| Parameter | Type | Description | Required |
|---|---|---|---|
| identityType | string | Specify the string value b2b. | Yes |
| identityValue | string | The Microsoft Store ID key that represents the identity of the user for whom you want to query products. | Yes |
| localTicketReference | string | The requested identifier for the returned products. Returned items in the response body will have a matching localTicketReference. We recommend that you use the same value as the userId claim in the Microsoft Store ID key. | Yes |
The ProductSkuId object contains the following parameters.
| Parameter | Type | Description | Required |
|---|---|---|---|
| productId | string | The Store ID for a product in the Microsoft Store catalog. An example Store ID for a product is 9NBLGGH42CFD. | Yes |
| skuId | string | The Store ID for a product's SKU in the Microsoft Store catalog. An example Store ID for a SKU is 0010. | Yes |
Request example
POST https://collections.mp.microsoft.com/v6.0/collections/query HTTP/1.1
Authorization: Bearer eyJ0eXAiOiJKV1Q…….
Host: collections.mp.microsoft.com
Content-Length: 2531
Content-Type: application/json
{
"maxPageSize": 100,
"beneficiaries": [
{
"localTicketReference": "1055521810674918",
"identityValue": "eyJ0eXAiOiJ……",
"identityType": "b2b"
}
],
"modifiedAfter": "\/Date(-62135568000000)\/",
"productSkuIds": [
{
"productId": "9NBLGGH5WVP6",
"skuId": "0010"
}
],
"productTypes": [
"UnmanagedConsumable"
],
"validityType": "All"
}
Response
Response body
| Parameter | Type | Description | Required |
|---|---|---|---|
| continuationToken | string | If there are multiple sets of products, this token is returned when the page limit is reached. You can specify this continuation token in subsequent calls to retrieve remaining products. | No |
| items | CollectionItemContractV6 | An array of products for the specified user. For more information, see the table below. | No |
The CollectionItemContractV6 object contains the following parameters.
| Parameter | Type | Description | Required |
|---|---|---|---|
| acquiredDate | datetime | The date on which the user acquired the item. | Yes |
| campaignId | string | The campaign ID that was provided at purchase time for this item. | No |
| devOfferId | string | The offer ID from an in-app purchase. | No |
| endDate | datetime | The end date of the item. | Yes |
| fulfillmentData | list<string> | N/A | No |
| inAppOfferToken | string | The developer-specified product ID string that is assigned to the item in Partner Center. An example product ID is product123. | No |
| itemId | string | An ID that identifies this collection item from other items the user owns. This ID is unique per product. | Yes |
| localTicketReference | string | The ID of the previously supplied localTicketReference in the request body. | Yes |
| modifiedDate | datetime | The date this item was last modified. | Yes |
| orderId | string | If present, the order ID of which this item was obtained. | No |
| orderLineItemId | string | If present, the line item of the particular order for which this item was obtained. | No |
| ownershipType | string | The string OwnedByBeneficiary. | Yes |
| productId | string | The Store ID for the product in the Microsoft Store catalog. An example Store ID for a product is 9NBLGGH42CFD. | Yes |
| productType | string | One of the following product types: Application, Durable, and UnmanagedConsumable. | Yes |
| purchasedCountry | string | N/A | No |
| purchaser | IdentityContractV6 | If present, this represents the identity of the purchaser of the item. See the details for this object below. | No |
| quantity | number | The quantity of the item. Currently, this will always be 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 |
| skuType | string | Type of the SKU. Possible values include Trial, Full, and Rental. | Yes |
| startDate | datetime | The date that the item starts being valid. | Yes |
| status | string | The status of the item. Possible values include Active, Expired, Revoked, and Banned. | Yes |
| tags | list<string> | N/A | Yes |
| transactionId | guid | The transaction ID as a result of the purchase of this item. Can be used for reporting an item as fulfilled. | Yes |
The IdentityContractV6 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 Microsoft Store ID key. | Yes |
Response example
HTTP/1.1 200 OK
Content-Length: 7241
Content-Type: application/json
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
MS-RequestId: a9988cf9-652b-4791-beba-b0e732121a12
MS-CV: xu2HW6SrSkyfHyFh.0.1
MS-ServerId: 020022359
Date: Tue, 22 Sep 2015 20:28:18 GMT
{
"items" : [
{
"acquiredDate" : "2015-09-22T19:22:51.2068724+00:00",
"devOfferId" : "f9587c53-540a-498b-a281-8a349491ed47",
"endDate" : "9999-12-31T23:59:59.9999999+00:00",
"fulfillmentData" : [],
"inAppOfferToken" : "consumable2",
"itemId" : "4b8fbb13127a41f299270ea668681c1d",
"localTicketReference" : "1055521810674918",
"modifiedDate" : "2015-09-22T19:22:51.2513155+00:00",
"orderId" : "4ba5960d-4ec6-4a81-ac20-aafce02ddf31",
"ownershipType" : "OwnedByBeneficiary",
"productId" : "9NBLGGH5WVP6",
"productType" : "UnmanagedConsumable",
"purchaser" : {
"identityType" : "pub",
"identityValue" : "user123"
},
"skuId" : "0010",
"skuType" : "Full",
"startDate" : "2015-09-22T19:22:51.2068724+00:00",
"status" : "Active",
"tags" : [],
"transactionId" : "4ba5960d-4ec6-4a81-ac20-aafce02ddf31"
}
]
}