XStoreQueryAssociatedProductsAsync
Gets store listing information for products that users can buy from within the current game.Syntax
Parameters
storeContextHandle _In_Type: XStoreContextHandle The store context handle for the user returned by XStoreCreateContext. productKinds _In_
Type: XStoreProductKind The type of products to return. maxItemsToRetrievePerPage _In_
Type: uint32_t The maximum number of items to retrieve per page. The number of items returned per page can vary from 0 to
maxItemsToRetrievePerPage.
For more information, see Paging.
async _Inout_Type: XAsyncBlock* An XAsyncBlock defining the asynchronous work being done. Use the XAsyncBlock to poll for the call’s status and retrieve call results. For more information, see XAsyncBlock.
Return value
Type: HRESULT HRESULT success or error code.Remarks
To get the store listing information and the execution result for this function, call XStoreQueryAssociatedProductsResult after calling this function. XStoreQueryAssociatedProductsResult contains anXStoreProductQueryHandle that you enumerate by calling XStoreEnumerateProductsQuery.
You can’t know the number of products that this query returns upfront.
This API only returns products that users can browse in the Microsoft Store or purchase within the game.
The results don’t include any product that is hidden, expired, or removed from the store.
If you need details for such a product, use XStoreQueryProductsAsync and pass in the product’s Store ID.
Paging
This function returns products across multiple pages (up tomaxItemsToRetrievePerPage items in a single page).
Use XStoreProductsQueryHasMorePages and XStoreProductsQueryNextPageAsync/XStoreProductsQueryNextPageResult to process all paged results.
Paging isn’t complete until XStoreProductsQueryHasMorePages returns false.
Paging can behave differently between sandboxes and RETAIL.
In a sandbox, items accumulate up to
maxItemsToRetrievePerPage before a page returns.
In RETAIL, it’s common to have 0-1 items return per page.It’s important for all games using this API to implement and test paging before release.To test paging behavior in a sandbox, temporarily set maxItemsToRetrievePerPage to a value less than the number of products published to your sandbox.
To test in RETAIL before your game’s release, publish products using the Enable Private Audience option on the ‘Pricing and availability’ page in Partner Center.
To test in RETAIL after your game’s release, use a package flight.Requirements
Header: XStore.h (included in XGameRuntime.h) Library: xgameruntime.lib Supported platforms: Windows, XBOX One family consoles, and XBOX Series consolesConceptual documentation
- Implement in-game purchases in your game
- Basic store operations
- Granting players access to add-on content
- GDK Commerce Systems Overview
- Fine Grained Rate Limiting for Microsoft Store APIs
- Store Development Entitlements Tool (DevEntitlementTool.exe)
See also
XStoreXStoreQueryAssociatedProductsResult
XStoreEnumerateProductsQuery
XStoreProductsQueryHasMorePages
XStoreProductsQueryNextPageAsync
Basic store operations
Granting players access to add-on content
