Inventory - Execute Inventory Operations
Execute a list of Inventory Operations. A maximum list of 10 operations can be performed by a single request. There is also a limit to 250 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 15 requests in 90 seconds and Title Entities limited to 500 requests in 10 seconds.
POST https://titleId.playfabapi.com/Inventory/ExecuteInventoryOperationsRequest 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 10 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 10 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 |
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