- Selecting the right Collections Query API for your needs
- Understanding satisfying entitlements in the response
- Understanding duplicate items in the response
Review Prerequisites for service-to-service APIs. If products aren’t correctly configured for your auth type, calls can succeed but return no results.
Selecting the right Collections Query API for your needs
There are two versions of Collections Query:b2bLicensePreview (v8) and publisherQuery (v9). In most cases, use publisherQuery because it has streamlined request parameters and supports XBOX Game Pass status. Use b2bLicensePreview when you need legacy behaviors such as LegacyProductId support.
Although there’s no v9 URI equivalent for consume functionality, you can use publisherQuery and the v8 consume URI together without issue.
Understanding satisfying entitlements in the response
A user can be entitled to a product directly (purchase/redeem) or indirectly (bundle/subscription). If the entitlement is indirect, thesatisfiedByProductIds array contains the ProductId(s) the entitlement is coming from.
Example: A user purchased the Deluxe Edition bundle of a game. Calling the Query APIs shows the game product and any included products in the bundle returned in the result. Each of these items have the ProductID of the Deluxe Edition bundle in their satisfiedByProductIds list.
Understanding duplicate items in the response
You might see multiple items with the same ProductId/SKU when users have multiple entitlement sources. Differences usually appear in fields such asacquisitionType, dates, and satisfiedByProductIds. Use excludeDuplicates as true to collapse multiple entitlement sources into one item with the most direct ownership entitlement in this order:
- Direct purchase / redeem code
- Satisfied by a bundle purchased directly
- Satisfied by a subscription
- Satisfied by a promotional purchase (Ex: Games With Gold)
Active and Expired subscription periods), only one item is returned (even if excludeDuplicates is off) using the following status priority:
ActiveInvalid(If multiple invalid entitlements, the most recently invalidated item would be returned)Revoked
Example
A user buys Game A and Add-on B, then later buys a Season Pass that also includes Add-on B. The response can contain two entries for add-on B: the direct purchase and the satisfied entitlement from the Season Pass. IfexcludeDuplicates is true, only the direct purchase entry is returned.