Catalog - Search Items
Executes a search against the public catalog using the provided search parameters and returns a set of paginated results. SearchItems uses a cache of the catalog with item updates taking up to a few minutes to propagate. You should use the GetItem API for when trying to immediately get recent item updates. More information about the Search API can be found here: https://learn.microsoft.com/en-us/gaming/playfab/features/economy-v2/catalog/search
POST https://titleId.playfabapi.com/Catalog/SearchItemsRequest Header
| Name | Required | Type | Description |
|---|---|---|---|
| X-EntityToken | True |
string |
This API requires an Entity Session Token, available from the Entity GetEntityToken method. |
Request Body
| Name | Required | Type | Description |
|---|---|---|---|
| Count | True |
number |
Number of items to retrieve. This value is optional. Maximum page size is 50. Default value is 10. |
| ContinuationToken |
string |
An opaque token used to retrieve the next page of items, if any are available. |
|
| CustomTags |
object |
The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.). |
|
| Entity |
The entity to perform this action on. |
||
| Filter |
string |
An OData filter used to refine the search query (For example: "type eq 'ugc'"). More info about Filter Complexity limits can be found here: https://learn.microsoft.com/en-us/gaming/playfab/features/economy-v2/catalog/search#limits |
|
| Language |
string |
The locale to be returned in the result. |
|
| OrderBy |
string |
An OData orderBy used to order the results of the search query. For example: "rating/average asc" |
|
| Search |
string |
The text to search for. |
|
| Select |
string |
An OData select query option used to augment the search results. If not defined, the default search result metadata will be returned. |
|
| Store |
The store to restrict the search request to. |
Responses
| Name | Type | Description |
|---|---|---|
| 200 OK | ||
| 400 Bad Request |
This is the outer wrapper for all responses with errors |
Security
X-EntityToken
This API requires an Entity Session Token, available from the Entity GetEntityToken method.
Type:
apiKey
In:
header
Definitions
| Name | Description |
|---|---|
|
Api |
The basic wrapper around every failed API response |
|
Catalog |
|
|
Catalog |
|
|
Catalog |
|
|
Catalog |
|
|
Catalog |
|
|
Catalog |
|
|
Catalog |
|
|
Catalog |
|
|
Catalog |
|
| Content | |
|
Deep |
|
|
Entity |
Combined entity type and ID structure which uniquely identifies a single entity. |
|
Filter |
|
| Image | |
|
Keyword |
|
|
Moderation |
|
|
Moderation |
|
| Permissions | |
| Rating | |
|
Search |
|
|
Search |
|
|
Store |
|
|
Store |
ApiErrorWrapper
The basic wrapper around every failed API response
| Name | Type | Description |
|---|---|---|
| code |
integer |
Numerical HTTP code |
| error |
string |
Playfab error code |
| errorCode |
integer |
Numerical PlayFab error code |
| errorDetails |
object |
Detailed description of individual issues with the request object |
| errorMessage |
string |
Description for the PlayFab errorCode |
| status |
string |
String HTTP code |
CatalogAlternateId
| Name | Type | Description |
|---|---|---|
| Type |
string |
Type of the alternate ID. |
| Value |
string |
Value of the alternate ID. |
CatalogItem
| Name | Type | Description |
|---|---|---|
| AlternateIds |
The alternate IDs associated with this item. An alternate ID can be set to 'FriendlyId' or any of the supported marketplace names. |
|
| ContentType |
string |
The client-defined type of the item. |
| Contents |
Content[] |
The set of content/files associated with this item. Up to 100 files can be added to an item. |
| CreationDate |
string |
The date and time when this item was created. |
| CreatorEntity |
The ID of the creator of this catalog item. |
|
| DeepLinks |
Deep |
The set of platform specific deep links for this item. |
| DefaultStackId |
string |
The Stack Id that will be used as default for this item in Inventory when an explicit one is not provided. This DefaultStackId can be a static stack id or '{guid}', which will generate a unique stack id for the item. If null, Inventory's default stack id will be used. |
| Description |
object |
A dictionary of localized descriptions. Key is language code and localized string is the value. The NEUTRAL locale is required. Descriptions have a 10000 character limit per country code. |
| DisplayProperties |
object |
Game specific properties for display purposes. This is an arbitrary JSON blob. The Display Properties field has a 10000 byte limit per item. |
| DisplayVersion |
string |
The user provided version of the item for display purposes. Maximum character length of 50. |
| ETag |
string |
The current ETag value that can be used for optimistic concurrency in the If-None-Match header. |
| EndDate |
string |
The date of when the item will cease to be available. If not provided then the product will be available indefinitely. |
| Id |
string |
The unique ID of the item. |
| Images |
Image[] |
The images associated with this item. Images can be thumbnails or screenshots. Up to 100 images can be added to an item. Only .png, .jpg, .gif, and .bmp file types can be uploaded |
| IsHidden |
boolean |
Indicates if the item is hidden. |
| ItemReferences |
The item references associated with this item. For example, the items in a Bundle/Store/Subscription. Every item can have up to 50 item references. |
|
| Keywords |
A dictionary of localized keywords. Key is language code and localized list of keywords is the value. Keywords have a 50 character limit per keyword and up to 32 keywords can be added per country code. |
|
| LastModifiedDate |
string |
The date and time this item was last updated. |
| Moderation |
The moderation state for this item. |
|
| Platforms |
string[] |
The platforms supported by this item. |
| PriceOptions |
The prices the item can be purchased for. |
|
| Rating |
Rating summary for this item. |
|
| StartDate |
string |
The date of when the item will be available. If not provided then the product will appear immediately. |
| StoreDetails |
Optional details for stores items. |
|
| Tags |
string[] |
The list of tags that are associated with this item. Up to 32 tags can be added to an item. |
| Title |
object |
A dictionary of localized titles. Key is language code and localized string is the value. The NEUTRAL locale is required. Titles have a 512 character limit per country code. |
| Type |
string |
The high-level type of the item. The following item types are supported: bundle, catalogItem, currency, store, ugc, subscription. |
CatalogItemReference
| Name | Type | Description |
|---|---|---|
| Amount |
number |
The amount of the catalog item. |
| Id |
string |
The unique ID of the catalog item. |
| PriceOptions |
The prices the catalog item can be purchased for. |
CatalogPrice
| Name | Type | Description |
|---|---|---|
| Amounts |
The amounts of the catalog item price. Each price can have up to 15 item amounts. |
|
| UnitAmount |
number |
The per-unit amount this price can be used to purchase. |
| UnitDurationInSeconds |
number |
The per-unit duration this price can be used to purchase. The maximum duration is 100 years. |
CatalogPriceAmount
| Name | Type | Description |
|---|---|---|
| Amount |
number |
The amount of the price. |
| ItemId |
string |
The Item Id of the price. |
CatalogPriceAmountOverride
| Name | Type | Description |
|---|---|---|
| FixedValue |
number |
The exact value that should be utilized in the override. |
| ItemId |
string |
The id of the item this override should utilize. |
| Multiplier |
number |
The multiplier that will be applied to the base Catalog value to determine what value should be utilized in the override. |
CatalogPriceOptions
| Name | Type | Description |
|---|---|---|
| Prices |
Prices of the catalog item. An item can have up to 15 prices |
CatalogPriceOptionsOverride
| Name | Type | Description |
|---|---|---|
| Prices |
The prices utilized in the override. |
CatalogPriceOverride
| Name | Type | Description |
|---|---|---|
| Amounts |
The currency amounts utilized in the override for a singular price. |
Content
| Name | Type | Description |
|---|---|---|
| Id |
string |
The content unique ID. |
| MaxClientVersion |
string |
The maximum client version that this content is compatible with. Client Versions can be up to 3 segments separated by periods(.) and each segment can have a maximum value of 65535. |
| MinClientVersion |
string |
The minimum client version that this content is compatible with. Client Versions can be up to 3 segments separated by periods(.) and each segment can have a maximum value of 65535. |
| Tags |
string[] |
The list of tags that are associated with this content. Tags must be defined in the Catalog Config before being used in content. |
| Type |
string |
The client-defined type of the content. Content Types must be defined in the Catalog Config before being used. |
| Url |
string |
The Azure CDN URL for retrieval of the catalog item binary content. |
DeepLink
| Name | Type | Description |
|---|---|---|
| Platform |
string |
Target platform for this deep link. |
| Url |
string |
The deep link for this platform. |
EntityKey
Combined entity type and ID structure which uniquely identifies a single entity.
| Name | Type | Description |
|---|---|---|
| Id |
string |
Unique ID of the entity. |
| Type |
string |
Entity type. See https://docs.microsoft.com/gaming/playfab/features/data/entities/available-built-in-entity-types |
FilterOptions
| Name | Type | Description |
|---|---|---|
| Filter |
string |
The OData filter utilized. Mutually exclusive with 'IncludeAllItems'. More info about Filter Complexity limits can be found here: https://learn.microsoft.com/en-us/gaming/playfab/features/economy-v2/catalog/search#limits |
| IncludeAllItems |
boolean |
The flag that overrides the filter and allows for returning all catalog items. Mutually exclusive with 'Filter'. |
Image
| Name | Type | Description |
|---|---|---|
| Id |
string |
The image unique ID. |
| Tag |
string |
The client-defined tag associated with this image. Tags must be defined in the Catalog Config before being used in images |
| Type |
string |
Images can be defined as either a "thumbnail" or "screenshot". There can only be one "thumbnail" image per item. |
| Url |
string |
The URL for retrieval of the image. |
KeywordSet
| Name | Type | Description |
|---|---|---|
| Values |
string[] |
A list of localized keywords. |
ModerationState
| Name | Type | Description |
|---|---|---|
| LastModifiedDate |
string |
The date and time this moderation state was last updated. |
| Reason |
string |
The current stated reason for the associated item being moderated. |
| Status |
The current moderation status for the associated item. |
ModerationStatus
| Name | Type | Description |
|---|---|---|
| Approved |
string |
|
| AwaitingModeration |
string |
|
| Rejected |
string |
|
| Unknown |
string |
Permissions
| Name | Type | Description |
|---|---|---|
| SegmentIds |
string[] |
The list of ids of Segments that the a player can be in to purchase from the store. When a value is provided, the player must be in at least one of the segments listed for the purchase to be allowed. |
Rating
| Name | Type | Description |
|---|---|---|
| Average |
number |
The average rating for this item. |
| Count1Star |
number |
The total count of 1 star ratings for this item. |
| Count2Star |
number |
The total count of 2 star ratings for this item. |
| Count3Star |
number |
The total count of 3 star ratings for this item. |
| Count4Star |
number |
The total count of 4 star ratings for this item. |
| Count5Star |
number |
The total count of 5 star ratings for this item. |
| TotalCount |
number |
The total count of ratings for this item. |
SearchItemsRequest
| Name | Type | Description |
|---|---|---|
| ContinuationToken |
string |
An opaque token used to retrieve the next page of items, if any are available. |
| Count |
number |
Number of items to retrieve. This value is optional. Maximum page size is 50. Default value is 10. |
| CustomTags |
object |
The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.). |
| Entity |
The entity to perform this action on. |
|
| Filter |
string |
An OData filter used to refine the search query (For example: "type eq 'ugc'"). More info about Filter Complexity limits can be found here: https://learn.microsoft.com/en-us/gaming/playfab/features/economy-v2/catalog/search#limits |
| Language |
string |
The locale to be returned in the result. |
| OrderBy |
string |
An OData orderBy used to order the results of the search query. For example: "rating/average asc" |
| Search |
string |
The text to search for. |
| Select |
string |
An OData select query option used to augment the search results. If not defined, the default search result metadata will be returned. |
| Store |
The store to restrict the search request to. |
SearchItemsResponse
| Name | Type | Description |
|---|---|---|
| ContinuationToken |
string |
An opaque token used to retrieve the next page of items, if any are available. |
| Items |
The paginated set of results for the search query. |
StoreDetails
| Name | Type | Description |
|---|---|---|
| FilterOptions |
The options for the filter in filter-based stores. These options are mutually exclusive with item references. |
|
| Permissions |
The permissions that control which players can purchase from the store. |
|
| PriceOptionsOverride |
The global prices utilized in the store. These options are mutually exclusive with price options in item references. |
StoreReference
| Name | Type | Description |
|---|---|---|
| AlternateId |
An alternate ID of the store. |
|
| Id |
string |
The unique ID of the store. |
Error Codes
| Name | Code |
|---|---|
| DatabaseThroughputExceeded | 1113 |
| ItemNotFound | 1047 |
| NotImplemented | 1515 |