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