Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
If your title is participating in the Game Pass subscriptions (either on Xbox or PC), your title's participation may may include granting Game Pass subscribers in-game perks. The collections.mp.microsoft.com/v9.0/collections/publisherQuery API provides the ability to check if the user is an active Game Pass subscriber and which subscription tier they have. Before your game service can query a user's Game Pass status, your publisher must apply for and obtain authorization for which Game Pass tier(s) you will need results for. Requesting permission for Game Pass subscription information is done through your Developer Partner Manager or Microsoft contact who will begin the approval process.
Response data behavior for authorized and non-authorized publishers
If your publisher is not authorized to view Game Pass subscription status, products entitled through Game Pass will appear as directly owned digital entitlements. The acquisitionType will be 'Single' and the Game Pass ProductId will not appear in the satisfiedByProductIds list.
For authorized publishers, only active Game Pass subscriptions will be returned. If the user's Game Pass subscription is canceled or ends, the query result will no longer contain the Game Pass information. Additionally, the StartDate and EndDate values are modified to always be the min and max values respectively. These values cannot be used to know when a user's subscription started or when it will end.
Game Pass release day delay in server-to-server entitlement results
When your title or DLC are scheduled to be included in Game Pass, there will be a delay between the moment users are able to launch the content and when calls to PublisherQuery will show results for your title or DLC. This is due to the catalog caches used by different store systems being updated at different intervals. When the Game Pass change is published to the catalog, the local licensing services will usually get the updated info first and then the caches used by PublisherQuery within two to three hours after. So please note that on launch day, there will be a few hours where users may be licensed and able to launch the game on the client, but your server-to-server calls to PublisherQuery will not yet return results for your specific title's products. Checking for the ProductIDs of the Game Pass tiers is not affected by this, only items that are added to Game Pass as a satisfying entitlement or included item.
Requesting Game Pass subscription status
To request the user's Game Pass subscription status, add the corresponding ProductIds of the subscription tiers you are authorized to view into the query request's productSkuIds list (see table below).
| Subscription Tier | ProductID |
|---|---|
| Xbox Game Pass Core | CFQ7TTC0K5DJ |
| Xbox Game Pass Standard | CFQ7TTC0P85B |
| Xbox Game Pass for Console | CFQ7TTC0K6L8 |
| PC Game Pass | CFQ7TTC0KGQ8 |
| Xbox Game Pass Ultimate | CFQ7TTC0KHS0 |
If the user has a subscription in the tier you requested, the query response will include an item with the ProductId of the corresponding Game Pass subscription tier. This is the recommended way to accurately check if the user is a Game Pass subscriber as filtering out duplicate entitlements may hide any items showing Game Pass entitlements behind directly purchased items (See example in the following section).
Xbox Game Pass Ultimate subscribers are entitled to all other subscription tiers and will return the corresponding tier level that your publisher is authorized to view.
Example: Our publisher is authorized for PC Game Pass tier information only. A user with an Xbox Game Pass Ultimate subscription would return the PC Game Pass result item in the response from PublisherQuery based on our tier access. If our publisher also had authorization to view Xbox Game Pass Ultimate tier, then the PublisherQuery result would include items for both PC Game Pass and Xbox Game Pass Ultimate.
Detecting products entitled through a Game Pass subscription with satisfiedByProductIds
Once your publisher is authorized to view Game Pass subscription information, you can distinguish which products are being enabled through the user's Game Pass subscription with the satisfiedByProductIds and acquisitionType fields. An item entitled through a Game Pass subscription will have the acquisitionType 'Recurring', and the satisfiedByProductIds list will have the productID of the corresponding Game Pass subscription.
Note: If you are using the excludeDuplicates filter option, the Game Pass related entitlement will be filtered out if the user owns the title directly. Therefore always including the Game Pass ProductId(s) in your PublisherQuery request is the recommended when checking for a Game Pass subscriber.
Duplicate Item Example with Xbox Game Pass
A publisher is on-boarded to view Game Pass info in their query parameters. The user has an active Xbox Game Pass Standard subscription giving them access to Game A. After a few weeks of playing the game, the user decides to purchase Game A with the Game Pass discount so that they own Game A forever. This will result in two items being returned for Game A's ProductId in the publisherQuery results, possibly with the same SKU. One item will show as being entitled through the Xbox Game Pass Standard ProductId in the SatisfiedByProductIds list and the AcquisitionType will be 'Recurring'. The other item will have an acquisitionType of 'Single' representing the direct purchase with an empty satisfiedByProductIds list (unless the purchase made was a game bundle).
If excludeDuplicates is enabled in the request body, then only the direct purchase version of the item will be returned as direct purchase or a game bundle take priority over a subscription entitlement.
See Understanding duplicate items in the Publisher Query response for more info.
Example request for Xbox Game Pass Standard subscription status
POST https://collections.mp.microsoft.com/v9.0/collections/PublisherQuery HTTP/1.1
{authorization header}
User-Agent: {identifier string of your service}
Content-Type: application/json;
Host: collections.mp.microsoft.com
{
"maxPageSize": 100,
"excludeDuplicates": true,
"validityType": "All",
"productSkuIds": [
{"productId": "CFQ7TTC0P85B"}
],
"beneficiaries": [
{
"identitytype": "b2b",
"identityValue": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxNTI2OEI4N0YwNEFDQzIzRDdCQ0E2M...",
"localTicketReference": ""
}
],
"sbx":"XDKS.1"
}
Example response for Xbox Game Pass Standard
HTTP/1.1 200 OK
Date: Mon, 15 Aug 2022 18:40:32 GMT
Content-Type: application/json; charset=utf-8
Server: Kestrel
Content-Length: 602
MS-CorrelationId: 5ec99421-7fa8-457e-87c1-edf16297528e
MS-RequestId: a604aca2-f60d-4de5-993f-125a57dcabdd
MS-CV: pjtLxeR5BUOY5n.0
X-Content-Type-Options: nosniff
MS-ServerId: c9cf4cd5b-4dhs
{
"items": [
{
"acquiredDate": "2022-08-15T18:29:24.2131463+00:00",
"acquisitionType": "Recurring",
"endDate": "9999-12-31T23:59:59.9999999+00:00",
"id": "a1702e2c6cff4e0095b3c51d06d9fac9",
"modifiedDate": "2022-08-15T18:29:24.2153924+00:00",
"productId": "CFQ7TTC0P85B",
"productKind": "Pass",
"quantity": 1,
"recurrenceData": "mdr:0:9ee54c66dc2a49ca81bd2c3eaf148826:a118bfe9-8175-4407-9d14-b2be4af30acd",
"satisfiedByProductIds": [],
"skuId": "",
"startDate": "2022-08-15T00:00:00+00:00",
"status": "Active",
"tags": [],
"transactionId": "a118bfe9-8175-4407-9d14-b2be4af30acd",
"trialData": {
"isInTrialPeriod": false,
"isTrial": false
}
}
]
}