Title-Wide Data Management - Set 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. Creates the catalog configuration of all virtual goods for the specified catalog version
POST https://titleId.playfabapi.com/Admin/SetCatalogItemsRequest Header
| Name | Required | Type | Description |
|---|---|---|---|
| X-SecretKey | True |
string |
This API requires a title secret key, available to title admins, from PlayFab Game Manager. |
Request Body
| Name | Type | Description |
|---|---|---|
| Catalog |
Array of catalog items to be submitted. Note that while CatalogItem has a parameter for CatalogVersion, it is not required and ignored in this call. |
|
| CatalogVersion |
string |
Which catalog is being updated. If null, uses the default catalog. |
| CustomTags |
object |
The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.). |
| SetAsDefaultCatalog |
boolean |
Should this catalog be set as the default catalog. Defaults to true. If there is currently no default catalog, this will always set it. |
Responses
| Name | Type | Description |
|---|---|---|
| 200 OK | ||
| 400 Bad Request |
This is the outer wrapper for all responses with errors |
Security
X-SecretKey
This API requires a title secret key, available to title admins, from PlayFab Game Manager.
Type:
apiKey
In:
header
Definitions
| Name | Description |
|---|---|
|
Api |
The basic wrapper around every failed API response |
|
Catalog |
A purchasable item from the item catalog |
|
Catalog |
|
|
Catalog |
|
|
Catalog |
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. |
|
Update |
When used for SetCatalogItems, this operation is not additive. Using it will cause the indicated catalog version to be created from scratch. If there is an existing catalog with the version number in question, it will be deleted and replaced with only the items specified in this call. When used for UpdateCatalogItems, this operation is additive. Items with ItemId values not currently in the catalog will be added, while those with ItemId values matching items currently in the catalog will overwrite those items with the given values. |
|
Update |
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 |
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 |
defines the consumable properties (number of uses, timeout) for the item |
|
| Container |
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 |
UpdateCatalogItemsRequest
When used for SetCatalogItems, this operation is not additive. Using it will cause the indicated catalog version to be created from scratch. If there is an existing catalog with the version number in question, it will be deleted and replaced with only the items specified in this call. When used for UpdateCatalogItems, this operation is additive. Items with ItemId values not currently in the catalog will be added, while those with ItemId values matching items currently in the catalog will overwrite those items with the given values.
| Name | Type | Description |
|---|---|---|
| Catalog |
Array of catalog items to be submitted. Note that while CatalogItem has a parameter for CatalogVersion, it is not required and ignored in this call. |
|
| CatalogVersion |
string |
Which catalog is being updated. If null, uses the default catalog. |
| CustomTags |
object |
The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.). |
| SetAsDefaultCatalog |
boolean |
Should this catalog be set as the default catalog. Defaults to true. If there is currently no default catalog, this will always set it. |
UpdateCatalogItemsResult
Error Codes
| Name | Code |
|---|---|
| InvalidDropTable | 1201 |
| InvalidItemId | 1093 |
| InvalidItemProperties | 1091 |
| InvalidJSONContent | 1200 |