Inventory - Execute Inventory Operations
Execute a list of Inventory Operations. A maximum list of 50 operations can be performed by a single request. There is also a limit to 300 items that can be modified/added in a single request. For example, adding a bundle with 50 items counts as 50 items modified. All operations must be done within a single inventory collection. This API has a reduced RPS compared to an individual inventory operation with Player Entities limited to 60 requests in 90 seconds.
POST https://titleId.playfabapi.com/Inventory/ExecuteInventoryOperations
Request 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 |
---|---|---|
CollectionId |
string |
The id of the entity's collection to perform this action on. (Default="default"). The number of inventory collections is unlimited. |
CustomTags |
object |
The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.). |
ETag |
string |
ETags are used for concurrency checking when updating resources. More information about using ETags can be found here: https://learn.microsoft.com/en-us/gaming/playfab/features/economy-v2/catalog/etags |
Entity |
The entity to perform this action on. |
|
IdempotencyId |
string |
The Idempotency ID for this request. Idempotency IDs can be used to prevent operation replay in the medium term but will be garbage collected eventually. |
Operations |
The operations to run transactionally. The operations will be executed in-order sequentially and will succeed or fail as a batch. Up to 50 operations can be added. |
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 |
---|---|
Add |
|
Alternate |
|
Api |
The basic wrapper around every failed API response |
Delete |
|
Entity |
Combined entity type and ID structure which uniquely identifies a single entity. |
Execute |
Execute a list of Inventory Operations for an Entity |
Execute |
|
Initial |
|
Inventory |
|
Inventory |
|
Inventory |
|
Purchase |
|
Purchase |
|
Subtract |
|
Transfer |
|
Update |
AddInventoryItemsOperation
Name | Type | Description |
---|---|---|
Amount |
number |
The amount to add to the current item amount. |
DurationInSeconds |
number |
The duration to add to the current item expiration date. |
Item |
The inventory item the operation applies to. |
|
NewStackValues |
The values to apply to a stack newly created by this operation. |
AlternateId
Name | Type | Description |
---|---|---|
Type |
string |
Type of the alternate ID. |
Value |
string |
Value of the alternate ID. |
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 |
DeleteInventoryItemsOperation
Name | Type | Description |
---|---|---|
Item |
The inventory item the operation applies to. |
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 |
ExecuteInventoryOperationsRequest
Execute a list of Inventory Operations for an Entity
Name | Type | Description |
---|---|---|
CollectionId |
string |
The id of the entity's collection to perform this action on. (Default="default"). The number of inventory collections is unlimited. |
CustomTags |
object |
The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.). |
ETag |
string |
ETags are used for concurrency checking when updating resources. More information about using ETags can be found here: https://learn.microsoft.com/en-us/gaming/playfab/features/economy-v2/catalog/etags |
Entity |
The entity to perform this action on. |
|
IdempotencyId |
string |
The Idempotency ID for this request. Idempotency IDs can be used to prevent operation replay in the medium term but will be garbage collected eventually. |
Operations |
The operations to run transactionally. The operations will be executed in-order sequentially and will succeed or fail as a batch. Up to 50 operations can be added. |
ExecuteInventoryOperationsResponse
Name | Type | Description |
---|---|---|
ETag |
string |
ETags are used for concurrency checking when updating resources. More information about using ETags can be found here: https://learn.microsoft.com/en-us/gaming/playfab/features/economy-v2/catalog/etags |
IdempotencyId |
string |
The idempotency id used in the request. |
TransactionIds |
string[] |
The ids of the transactions that occurred as a result of the request. |
InitialValues
Name | Type | Description |
---|---|---|
DisplayProperties |
object |
Game specific properties for display purposes. The Display Properties field has a 1000 byte limit. |
InventoryItem
Name | Type | Description |
---|---|---|
Amount |
number |
The amount of the item. |
DisplayProperties |
object |
Game specific properties for display purposes. This is an arbitrary JSON blob. The Display Properties field has a 1000 byte limit. |
ExpirationDate |
string |
Only used for subscriptions. The date of when the item will expire in UTC. |
Id |
string |
The id of the item. This should correspond to the item id in the catalog. |
StackId |
string |
The stack id of the item. |
Type |
string |
The type of the item. This should correspond to the item type in the catalog. |
InventoryItemReference
Name | Type | Description |
---|---|---|
AlternateId |
The inventory item alternate id the request applies to. |
|
Id |
string |
The inventory item id the request applies to. |
StackId |
string |
The inventory stack id the request should redeem to. (Default="default") |
InventoryOperation
Name | Type | Description |
---|---|---|
Add |
The add operation. |
|
Delete |
The delete operation. |
|
Purchase |
The purchase operation. |
|
Subtract |
The subtract operation. |
|
Transfer |
The transfer operation. |
|
Update |
The update operation. |
PurchaseInventoryItemsOperation
Name | Type | Description |
---|---|---|
Amount |
number |
The amount to purchase. |
DeleteEmptyStacks |
boolean |
Indicates whether stacks reduced to an amount of 0 during the operation should be deleted from the inventory. (Default = false) |
DurationInSeconds |
number |
The duration to purchase. |
Item |
The inventory item the operation applies to. |
|
NewStackValues |
The values to apply to a stack newly created by this operation. |
|
PriceAmounts |
The per-item price the item is expected to be purchased at. This must match a value configured in the Catalog or specified Store. |
|
StoreId |
string |
The id of the Store to purchase the item from. |
PurchasePriceAmount
Name | Type | Description |
---|---|---|
Amount |
number |
The amount of the inventory item to use in the purchase . |
ItemId |
string |
The inventory item id to use in the purchase . |
StackId |
string |
The inventory stack id the to use in the purchase. Set to "default" by default |
SubtractInventoryItemsOperation
Name | Type | Description |
---|---|---|
Amount |
number |
The amount to subtract from the current item amount. |
DeleteEmptyStacks |
boolean |
Indicates whether stacks reduced to an amount of 0 during the request should be deleted from the inventory. (Default = false). |
DurationInSeconds |
number |
The duration to subtract from the current item expiration date. |
Item |
The inventory item the operation applies to. |
TransferInventoryItemsOperation
Name | Type | Description |
---|---|---|
Amount |
number |
The amount to transfer. |
DeleteEmptyStacks |
boolean |
Indicates whether stacks reduced to an amount of 0 during the operation should be deleted from the inventory. (Default = false) |
GivingItem |
The inventory item the operation is transferring from. |
|
NewStackValues |
The values to apply to a stack newly created by this operation. |
|
ReceivingItem |
The inventory item the operation is transferring to. |
UpdateInventoryItemsOperation
Name | Type | Description |
---|---|---|
Item |
The inventory item to update with the specified values. |
Error Codes
Name | Code |
---|---|
DatabaseThroughputExceeded | 1113 |
InsufficientFunds | 1059 |
InvalidCatalogItemConfiguration | 4015 |
ItemNotFound | 1047 |