Inventory - Execute Transfer Operations
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/ExecuteTransferOperationsRequest 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 |
The entity the request is transferring from. Set to the caller by default. |
|
| IdempotencyId |
string |
The idempotency id for the request. |
| Operations |
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 |
The entity the request is transferring to. Set to the caller by default. |
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 |
|---|---|
|
Alternate |
|
|
Api |
The basic wrapper around every failed API response |
|
Entity |
Combined entity type and ID structure which uniquely identifies a single entity. |
|
Execute |
Transfer the specified list of inventory items of an entity's container Id to another entity's container Id. |
|
Execute |
|
|
Initial |
|
|
Inventory |
|
|
Transfer |
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 |
The entity the request is transferring from. Set to the caller by default. |
|
| IdempotencyId |
string |
The idempotency id for the request. |
| Operations |
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 |
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 |
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 |
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. |
Error Codes
| Name | Code |
|---|---|
| DatabaseThroughputExceeded | 1113 |
| InsufficientFunds | 1059 |
| 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