Inventory - Execute Transfer Operations

Reference

Service:: Economy

API Version:: 241122

Transfer a list of inventory items. A maximum list of 50 operations can be performed by a single request. When the response code is 202, one or more operations did not complete within the timeframe of the request. You can identify the pending operations by looking for OperationStatus = 'InProgress'. You can check on the operation status at anytime within 1 day of the request by passing the TransactionToken to the GetInventoryOperationStatus API.

POST https://titleId.playfabapi.com/Inventory/ExecuteTransferOperations

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
CustomTags	object	The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.).
GivingCollectionId	string	The inventory collection id the request is transferring from. (Default="default")
GivingETag	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
GivingEntity	EntityKey	The entity the request is transferring from. Set to the caller by default.
IdempotencyId	string	The idempotency id for the request.
Operations	TransferInventoryItemsOperation[]	The transfer 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.
ReceivingCollectionId	string	The inventory collection id the request is transferring to. (Default="default")
ReceivingEntity	EntityKey	The entity the request is transferring to. Set to the caller by default.

Responses

Name	Type	Description
200 OK	ExecuteTransferOperationsResponse
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
AlternateId
ApiErrorWrapper	The basic wrapper around every failed API response
EntityKey	Combined entity type and ID structure which uniquely identifies a single entity.
ExecuteTransferOperationsRequest	Transfer the specified list of inventory items of an entity's container Id to another entity's container Id.
ExecuteTransferOperationsResponse
InitialValues
InventoryItemReference
TransferInventoryItemsOperation

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

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

ExecuteTransferOperationsRequest

Transfer the specified list of inventory items of an entity's container Id to another entity's container Id.

Name	Type	Description
CustomTags	object	The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.).
GivingCollectionId	string	The inventory collection id the request is transferring from. (Default="default")
GivingETag	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
GivingEntity	EntityKey	The entity the request is transferring from. Set to the caller by default.
IdempotencyId	string	The idempotency id for the request.
Operations	TransferInventoryItemsOperation[]	The transfer 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.
ReceivingCollectionId	string	The inventory collection id the request is transferring to. (Default="default")
ReceivingEntity	EntityKey	The entity the request is transferring to. Set to the caller by default.

ExecuteTransferOperationsResponse

Name	Type	Description
GivingETag	string	ETags are used for concurrency checking when updating resources (before transferring from). This value will be empty if the operation has not completed yet. More information about using ETags can be found here: https://learn.microsoft.com/en-us/gaming/playfab/features/economy-v2/catalog/etags
GivingTransactionIds	string[]	The ids of transactions that occurred as a result of the request's giving action.
IdempotencyId	string	The Idempotency ID for this request.
OperationStatus	string	The transfer operation status. Possible values are 'InProgress' or 'Completed'. If the operation has completed, the response code will be 200. Otherwise, it will be 202.
OperationToken	string	The token that can be used to get the status of the transfer operation. This will only have a value if OperationStatus is 'InProgress'.
ReceivingETag	string	ETags are used for concurrency checking when updating resources (before transferring to). This value will be empty if the operation has not completed yet.
ReceivingTransactionIds	string[]	The ids of transactions that occurred as a result of the request's receiving action.

InitialValues

Name	Type	Description
DisplayProperties	object	Game specific properties for display purposes. The Display Properties field has a 1000 byte limit.

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")

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.

Error Codes

Name	Code
DatabaseThroughputExceeded	1113
InsufficientFunds	1059
ItemNotFound	1047

Share via