Skip to main content

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 an XStoreProductQueryHandle 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 to maxItemsToRetrievePerPage 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.
The following code shows how to retrieve product query results across multiple pages. Ensure the query handle is passed down through the paging recursion to avoid leaks.

Requirements

Header: XStore.h (included in XGameRuntime.h) Library: xgameruntime.lib Supported platforms: Windows, XBOX One family consoles, and XBOX Series consoles

Conceptual documentation

See also

XStore
XStoreQueryAssociatedProductsResult
XStoreEnumerateProductsQuery
XStoreProductsQueryHasMorePages
XStoreProductsQueryNextPageAsync
Basic store operations
Granting players access to add-on content
Last modified on October 19, 2026