Title-Wide Data Management - Get Catalog Items

NOTE: This is a Legacy Economy API, and is in bugfix-only mode. All new Economy features are being developed only for version 2. Retrieves the specified version of the title's catalog of virtual goods, including all defined properties

POST https://titleId.playfabapi.com/Client/GetCatalogItems

Request Header

Name Required Type Description
X-Authorization True

string

This API requires a client session ticket, available from any Client Login function.

Request Body

Name Type Description
CatalogVersion

string

Which catalog is being requested. If null, uses the default catalog.

Responses

Name Type Description
200 OK

GetCatalogItemsResult

If CatalogVersion is not specified, only inventory items associated with the most recent version of the catalog will be returned.

400 Bad Request

ApiErrorWrapper

This is the outer wrapper for all responses with errors

Security

X-Authorization

This API requires a client session ticket, available from any Client Login function.

Type: apiKey
In: header

Definitions

Name Description
ApiErrorWrapper

The basic wrapper around every failed API response

CatalogItem

A purchasable item from the item catalog

CatalogItemBundleInfo
CatalogItemConsumableInfo
CatalogItemContainerInfo

Containers are inventory items that can hold other items defined in the catalog, as well as virtual currency, which is added to the player inventory when the container is unlocked, using the UnlockContainerItem API. The items can be anything defined in the catalog, as well as RandomResultTable objects which will be resolved when the container is unlocked. Containers and their keys should be defined as Consumable (having a limited number of uses) in their catalog defintiions, unless the intent is for the player to be able to re-use them infinitely.

GetCatalogItemsRequest
GetCatalogItemsResult

If CatalogVersion is not specified, only inventory items associated with the most recent version of the catalog will be returned.

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

CatalogItem

A purchasable item from the item catalog

Name Type Description
Bundle

CatalogItemBundleInfo

defines the bundle properties for the item - bundles are items which contain other items, including random drop tables and virtual currencies

CanBecomeCharacter

boolean

if true, then an item instance of this type can be used to grant a character to a user.

CatalogVersion

string

catalog version for this item

Consumable

CatalogItemConsumableInfo

defines the consumable properties (number of uses, timeout) for the item

Container

CatalogItemContainerInfo

defines the container properties for the item - what items it contains, including random drop tables and virtual currencies, and what item (if any) is required to open it via the UnlockContainerItem API

CustomData

string

game specific custom data

Description

string

text description of item, to show in-game

DisplayName

string

text name for the item, to show in-game

InitialLimitedEditionCount

number

If the item has IsLImitedEdition set to true, and this is the first time this ItemId has been defined as a limited edition item, this value determines the total number of instances to allocate for the title. Once this limit has been reached, no more instances of this ItemId can be created, and attempts to purchase or grant it will return a Result of false for that ItemId. If the item has already been defined to have a limited edition count, or if this value is less than zero, it will be ignored.

IsLimitedEdition

boolean

BETA: If true, then only a fixed number can ever be granted.

IsStackable

boolean

if true, then only one item instance of this type will exist and its remaininguses will be incremented instead. RemainingUses will cap out at Int32.Max (2,147,483,647). All subsequent increases will be discarded

IsTradable

boolean

if true, then an item instance of this type can be traded between players using the trading APIs

ItemClass

string

class to which the item belongs

ItemId

string

unique identifier for this item

ItemImageUrl

string

URL to the item image. For Facebook purchase to display the image on the item purchase page, this must be set to an HTTP URL.

RealCurrencyPrices

object

override prices for this item for specific currencies

Tags

string[]

list of item tags

VirtualCurrencyPrices

object

price of this item in virtual currencies and "RM" (the base Real Money purchase price, in USD pennies)

CatalogItemBundleInfo

Name Type Description
BundledItems

string[]

unique ItemId values for all items which will be added to the player inventory when the bundle is added

BundledResultTables

string[]

unique TableId values for all RandomResultTable objects which are part of the bundle (random tables will be resolved and add the relevant items to the player inventory when the bundle is added)

BundledVirtualCurrencies

object

virtual currency types and balances which will be added to the player inventory when the bundle is added

CatalogItemConsumableInfo

Name Type Description
UsageCount

number

number of times this object can be used, after which it will be removed from the player inventory

UsagePeriod

number

duration in seconds for how long the item will remain in the player inventory - once elapsed, the item will be removed (recommended minimum value is 5 seconds, as lower values can cause the item to expire before operations depending on this item's details have completed)

UsagePeriodGroup

string

all inventory item instances in the player inventory sharing a non-null UsagePeriodGroup have their UsagePeriod values added together, and share the result - when that period has elapsed, all the items in the group will be removed

CatalogItemContainerInfo

Containers are inventory items that can hold other items defined in the catalog, as well as virtual currency, which is added to the player inventory when the container is unlocked, using the UnlockContainerItem API. The items can be anything defined in the catalog, as well as RandomResultTable objects which will be resolved when the container is unlocked. Containers and their keys should be defined as Consumable (having a limited number of uses) in their catalog defintiions, unless the intent is for the player to be able to re-use them infinitely.

Name Type Description
ItemContents

string[]

unique ItemId values for all items which will be added to the player inventory, once the container has been unlocked

KeyItemId

string

ItemId for the catalog item used to unlock the container, if any (if not specified, a call to UnlockContainerItem will open the container, adding the contents to the player inventory and currency balances)

ResultTableContents

string[]

unique TableId values for all RandomResultTable objects which are part of the container (once unlocked, random tables will be resolved and add the relevant items to the player inventory)

VirtualCurrencyContents

object

virtual currency types and balances which will be added to the player inventory when the container is unlocked

GetCatalogItemsRequest

Name Type Description
CatalogVersion

string

Which catalog is being requested. If null, uses the default catalog.

GetCatalogItemsResult

If CatalogVersion is not specified, only inventory items associated with the most recent version of the catalog will be returned.

Name Type Description
Catalog

CatalogItem[]

Array of items which can be purchased.