> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Detect XBOX Game Pass subscription access from your service

> Detect XBOX Game Pass subscription status from your service using the collections publisherQuery API, and grant rewards to active subscribers.

If your title participates in Game Pass, your service can use the [collections.mp.microsoft.com/v9.0/collections/publisherQuery API](/reference/microsoft-store-apis/xstore-v9-query-for-products) to verify active subscriber status to grant in-game rewards and perks. Before querying Game Pass status, your publisher must be authorized for the tiers you want to check. Request this authorization through your Developer Partner Manager or Microsoft contact.

## Game Pass licenses in client license checks

Game Pass entitlements can't be detected from the game client. When a user is entitled to your title through Game Pass, [XStoreQueryGameLicenseAsync](/reference/system/xstore/functions/xstorequerygamelicenseasync) returns a license with `isActive = true`, the same as a direct purchase. The [XStoreGameLicense](/reference/system/xstore/structs/xstoregamelicense) struct doesn't include a field that identifies how the license was acquired.

To record how users acquired your title, for example for telemetry, send the user's identity from your client to your own service. Your service then calls the publisherQuery API and checks `acquisitionType`. A value of `Recurring` indicates a Game Pass entitlement, and `Single` indicates direct ownership.

## Response data behavior for authorized and unauthorized publishers

If your publisher isn't authorized, Game Pass-entitled items appear as directly owned entitlements. For example, `acquisitionType` appears as `Single`, and Game Pass ProductIds don't appear in `satisfiedByProductIds`.

For authorized publishers, only active Game Pass subscriptions are returned. If the user's Game Pass subscription is canceled or ends, further queries will no longer contain the Game Pass information. Also, the `EndDate` is normalized to max value so it can't be used for subscription end detection.

## Game Pass release day delay in server-to-server entitlement results

When titles or add-ons go live in Game Pass, expect a delay between client availability and `publisherQuery` visibility. This behavior is due to different cache refresh intervals across store systems. In practice, local licensing usually updates first, and publisherQuery can lag by two to three hours.

Direct checks for Game Pass ProductIds aren't affected; the delay is mainly for items granted via satisfying entitlements.

## Testing Game Pass subscriptions in your development sandbox

The XBOX Game Pass tiers should be enabled and accessible by searching for them in the XBOX Store app within your development sandbox. XBOX test accounts are created with a test credit card and will be able to subscribe to the Game Pass tiers in your sandbox. If you are unable to find the Game Pass tiers in your sandbox, contact your Developer Partner Manager or Microsoft Contact for assistance.

<Note>
  Game Pass subscription status will not carry over between sandboxes. When adding Game Pass to a test account in a sandbox, do not move that test account into another sandbox for Game Pass or other commerce related testing or debugging.
</Note>

## Requesting Game Pass subscription status

To request the user's Game Pass subscription status, add the corresponding ProductIds of the subscription tiers you're authorized to view into the query request's productSkuIds list (see table).

| Subscription Tier                    | ProductID    |
| ------------------------------------ | ------------ |
| XBOX Game Pass for Console (retired) | CFQ7TTC0K6L8 |
| XBOX Game Pass (Starter Edition)     | CFQ7TTC10QFD |
| PC Game Pass                         | CFQ7TTC0KGQ8 |
| XBOX Game Pass Essential             | CFQ7TTC0K5DJ |
| XBOX Game Pass Premium               | CFQ7TTC0P85B |
| XBOX Game Pass Ultimate              | CFQ7TTC0KHS0 |

If the user has a subscription in the tier you requested, the query response includes an item with the ProductId of the corresponding Game Pass subscription tier.

### Behavior requesting tiers included in higher tiers

Some Game Pass tiers are included when a subscriber has a higher tier. Any of your authorized tiers that are included in higher tiers are returned when the user is subscribed to the higher tier.

Example: Our publisher is authorized for XBOX Game Pass Essential. The user has XBOX Game Pass Ultimate and when you query for all Game Pass ProductIds, publisherQuery only returns a result for XBOX Game Pass Essential. If your publisher has access to view any of the other tiers, those tiers would also be returned.

<Note>
  XBOX Game Pass (Starter Edition) is an exception to inheritance and is a stand-alone tier. It isn't included in any of the other tiers.
</Note>

### Granting in-game perks for Game Pass subscribers

We recommend requesting access to the lowest Game Pass tier needed to grant in-game perks and benefits to subscribers.

Example: You're granting an in-game reward to all Game Pass subscribers on the console. You only need access to XBOX Game Pass Essential (CFQ7TTC0K5DJ) because Premium and Ultimate include Essential.

### Detecting products entitled through a Game Pass subscription with satisfiedByProductIds

After authorization, identify Game Pass-derived entitlements by checking the `satisfiedByProductIds` and `acquisitionType` values. A Game Pass-based entitlement has an `acquisitionType` of `Recurring` and `satisfiedByProductIds` will include the ProductID of the highest Game Pass tier you are authorized for.

<Note>
  If you're using the excludeDuplicates filter option, the Game Pass related entitlement is filtered out if the user owns the title directly.
</Note>

Checking `satisfiedByProductIds` of an item for Game Pass productIDs will tell you if the item is entitled through Game Pass, but is not sufficient to determine if the user is a Game Pass member. Therefore, when checking a user's Game Pass subscription status it is best to include the Game Pass ProductId values in the `productSkuIds` of your request.

### Duplicate item example with XBOX Game Pass

If the user has both direct ownership and Game Pass entitlement for the same product, two entries can appear when `excludeDuplicates` is `false`. When `excludeDuplicates` is `true`, the direct-purchase item is returned.

For full duplicate-resolution rules and source-priority behavior, see [Understanding duplicate items in the response](/publishing/xstore-commerce/xstore-query-entitlements#understanding-duplicate-items-in-the-response).

### Example request for XBOX Game Pass Essential subscription status

```json theme={null}
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": "CFQ7TTC0K5DJ"}
  ],
  "beneficiaries": [
    {
      "identitytype": "b2b",
      "identityValue": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxNTI2OEI4N0YwNEFDQzIzRDdCQ0E2M...",
      "localTicketReference": ""
    }
  ],
  "sbx":"RETAIL"
}
```

### Example response for XBOX Game Pass Essential

```json theme={null}
HTTP/1.1 200 OK
Date: Mon, 18 May 2026 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

{
 "items": [
  {
   "acquiredDate": "2026-05-15T18:29:24.2131463+00:00",
   "acquisitionType": "Recurring",
   "endDate": "9999-12-31T23:59:59.9999999+00:00",
   "id": "a1702e2c6cff4e0095b3c51d06d9fac9",
   "modifiedDate": "2026-05-15T18:29:24.2153924+00:00",
   "productId": "CFQ7TTC0K5DJ",
   "productKind": "Pass",
   "quantity": 1,
   "recurrenceData": "mdr:0:9ee54c66dc2a49ca81bd2c3eaf148826:a118bfe9-8175-4407-9d14-b2be4af30acd",
   "satisfiedByProductIds": [],
   "skuId": "",
   "startDate": "2026-05-15T00:00:00+00:00",
   "status": "Active",
   "tags": [],
   "transactionId": "a118bfe9-8175-4407-9d14-b2be4af30acd",
   "trialData": {
    "isInTrialPeriod": false,
    "isTrial": false
   }
  }
 ]
}
```

### Example request for game entitled through Game Pass Essential subscription

```json theme={null}
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": "9NTL0QDWZ4FS"}
  ],
  "beneficiaries": [
    {
      "identitytype": "b2b",
      "identityValue": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjYxNTI2OEI4N0YwNEFDQzIzRDdCQ0E2M...",
      "localTicketReference": ""
    }
  ],
  "sbx":"RETAIL"
}
```

### Example response for game entitled through Game Pass Essential subscription

```json theme={null}
HTTP/1.1 200 OK
Date: Mon, 18 May 2026 18:41:18 GMT
Content-Type: application/json; charset=utf-8
Server: Kestrel
Content-Length: 602
MS-CorrelationId: d4c6dd08-a80a-4098-9433-757864d3716d
MS-RequestId: 6de32c62-9690-46dc-81c3-d1fef9df10a5
MS-CV: IvL+PCZ9Jk2+C4Xo.0
X-Content-Type-Options: nosniff

{
 "items": [
  {
   "acquiredDate": "2026-05-15T18:29:24.2131463+00:00",
   "acquisitionType": "Recurring",
   "endDate": "9999-12-31T23:59:59.9999999+00:00",
   "id": "a1702e2c6cff4e0095b3c51d06d9fac9",
   "modifiedDate": "2026-05-15T18:29:24.2153924+00:00",
   "productId": "9NTL0QDWZ4FS",
   "productKind": "Game",
   "quantity": 1,
   "satisfiedByProductIds": [
     "CFQ7TTC0K5DJ"  
   ],
   "skuId": "0010",
   "startDate": "2026-05-15T00:00:00+00:00",
   "status": "Active",
   "tags": [],
   "transactionId": "a118bfe9-8175-4407-9d14-b2be4af30acd",
   "trialData": {
    "isInTrialPeriod": false,
    "isTrial": false
   }
  }
 ]
}
```

## See also

[Commerce Overview](/publishing/xstore-commerce/xstore-commerce-overview)

[XStore API reference](/reference/system/xstore/xstore_members)


## Related topics

- [Basic DRM and license checks](/publishing/xstore-commerce/xstore-basic-drm.md)
- [Granting players access to add-on content](/publishing/xstore-commerce/xstore-granting-access.md)
- [collections.mp.microsoft.com/v9.0/collections/publisherQuery](/reference/microsoft-store-apis/xstore-v9-query-for-products.md)
- [Client-side use of XBOX services user privileges](/services/xbox-services/fundamentals/identity/privileges/concepts/live-user-privileges-client.md)
- [Managing subscription products from your service](/publishing/xstore-commerce/xstore-managing-subscriptions.md)