Catalog - Get Items
Retrieves items from the public catalog. Up to 50 items can be returned at once. GetItems does not work off a cache of the Catalog and should be used when trying to get recent item updates. However, please note that item references data is cached and may take a few moments for changes to propagate.
POST https://titleId.playfabapi.com/Catalog/GetItemsRequest 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 | Type | Description |
|---|---|---|
| AlternateIds |
List of item alternate IDs. |
|
| 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. |
|
| Ids |
string[] |
List of Item Ids. |
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 |
|
|
Get |
|
|
Get |
|
| Image | |
|
Keyword |
|
|
Moderation |
|
|
Moderation |
|
| Permissions | |
| Rating | |
|
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'. |
GetItemsRequest
| Name | Type | Description |
|---|---|---|
| AlternateIds |
List of item alternate IDs. |
|
| 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. |
|
| Ids |
string[] |
List of Item Ids. |
GetItemsResponse
| Name | Type | Description |
|---|---|---|
| Items |
Metadata of set of items. |
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. |
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. |
Error Codes
| Name | Code |
|---|---|
| ItemNotFound | 1047 |
| NotImplemented | 1515 |
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for