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

EntityKey

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

InventoryOperation[]

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

ExecuteInventoryOperationsResponse

400 Bad Request

ApiErrorWrapper

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
AddInventoryItemsOperation
AlternateId
ApiErrorWrapper

The basic wrapper around every failed API response

DeleteInventoryItemsOperation
EntityKey

Combined entity type and ID structure which uniquely identifies a single entity.

ExecuteInventoryOperationsRequest

Execute a list of Inventory Operations for an Entity

ExecuteInventoryOperationsResponse
InitialValues
InventoryItem
InventoryItemReference
InventoryOperation
PurchaseInventoryItemsOperation
PurchasePriceAmount
SubtractInventoryItemsOperation
TransferInventoryItemsOperation
UpdateInventoryItemsOperation

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

InventoryItemReference

The inventory item the operation applies to.

NewStackValues

InitialValues

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

InventoryItemReference

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

EntityKey

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

InventoryOperation[]

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

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

AddInventoryItemsOperation

The add operation.

Delete

DeleteInventoryItemsOperation

The delete operation.

Purchase

PurchaseInventoryItemsOperation

The purchase operation.

Subtract

SubtractInventoryItemsOperation

The subtract operation.

Transfer

TransferInventoryItemsOperation

The transfer operation.

Update

UpdateInventoryItemsOperation

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

InventoryItemReference

The inventory item the operation applies to.

NewStackValues

InitialValues

The values to apply to a stack newly created by this operation.

PriceAmounts

PurchasePriceAmount[]

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

InventoryItemReference

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

InventoryItemReference

The inventory item the operation is transferring from.

NewStackValues

InitialValues

The values to apply to a stack newly created by this operation.

ReceivingItem

InventoryItemReference

The inventory item the operation is transferring to.

UpdateInventoryItemsOperation

Name Type Description
Item

InventoryItem

The inventory item to update with the specified values.

Error Codes

Name Code
DatabaseThroughputExceeded 1113
InsufficientFunds 1059
InvalidCatalogItemConfiguration 4015
ItemNotFound 1047