Transfer Inventory Items

Transfer inventory items. When transferring across collections, a 202 response indicates that the transfer 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. More information about item transfer scenarios can be found here: https://learn.microsoft.com/en-us/gaming/playfab/features/economy-v2/inventory/?tabs=inventory-game-manager#transfer-inventory-items

Allowed entity token types: title, master_player_account, title_player_account

Error codes

This operation may return the following PlayFab errors:

Error	Code
DatabaseThroughputExceeded	1113
InsufficientFunds	1059
ItemNotFound	1047
PreconditionFailed	1610

POST

Inventory

TransferInventoryItems

Transfer Inventory Items

curl --request POST \
  --url https://{titleId}.playfabapi.com/Inventory/TransferInventoryItems \
  --header 'Content-Type: application/json' \
  --header 'X-EntityToken: <api-key>' \
  --data '
{
  "GivingItem": {
    "Id": "11111111-1111-1111-1111-111111111111"
  },
  "ReceivingItem": {
    "Id": "11111111-1111-1111-1111-111111111111"
  },
  "Amount": 1,
  "GivingCollectionId": "default",
  "ReceivingCollectionId": "backpack"
}
'

import requests

url = "https://{titleId}.playfabapi.com/Inventory/TransferInventoryItems"

payload = {
    "GivingItem": { "Id": "11111111-1111-1111-1111-111111111111" },
    "ReceivingItem": { "Id": "11111111-1111-1111-1111-111111111111" },
    "Amount": 1,
    "GivingCollectionId": "default",
    "ReceivingCollectionId": "backpack"
}
headers = {
    "X-EntityToken": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-EntityToken': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    GivingItem: {Id: '11111111-1111-1111-1111-111111111111'},
    ReceivingItem: {Id: '11111111-1111-1111-1111-111111111111'},
    Amount: 1,
    GivingCollectionId: 'default',
    ReceivingCollectionId: 'backpack'
  })
};

fetch('https://{titleId}.playfabapi.com/Inventory/TransferInventoryItems', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{titleId}.playfabapi.com/Inventory/TransferInventoryItems",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'GivingItem' => [
        'Id' => '11111111-1111-1111-1111-111111111111'
    ],
    'ReceivingItem' => [
        'Id' => '11111111-1111-1111-1111-111111111111'
    ],
    'Amount' => 1,
    'GivingCollectionId' => 'default',
    'ReceivingCollectionId' => 'backpack'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-EntityToken: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{titleId}.playfabapi.com/Inventory/TransferInventoryItems"

	payload := strings.NewReader("{\n  \"GivingItem\": {\n    \"Id\": \"11111111-1111-1111-1111-111111111111\"\n  },\n  \"ReceivingItem\": {\n    \"Id\": \"11111111-1111-1111-1111-111111111111\"\n  },\n  \"Amount\": 1,\n  \"GivingCollectionId\": \"default\",\n  \"ReceivingCollectionId\": \"backpack\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-EntityToken", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{titleId}.playfabapi.com/Inventory/TransferInventoryItems")
  .header("X-EntityToken", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"GivingItem\": {\n    \"Id\": \"11111111-1111-1111-1111-111111111111\"\n  },\n  \"ReceivingItem\": {\n    \"Id\": \"11111111-1111-1111-1111-111111111111\"\n  },\n  \"Amount\": 1,\n  \"GivingCollectionId\": \"default\",\n  \"ReceivingCollectionId\": \"backpack\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{titleId}.playfabapi.com/Inventory/TransferInventoryItems")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-EntityToken"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"GivingItem\": {\n    \"Id\": \"11111111-1111-1111-1111-111111111111\"\n  },\n  \"ReceivingItem\": {\n    \"Id\": \"11111111-1111-1111-1111-111111111111\"\n  },\n  \"Amount\": 1,\n  \"GivingCollectionId\": \"default\",\n  \"ReceivingCollectionId\": \"backpack\"\n}"

response = http.request(request)
puts response.read_body

{
  "code": 200,
  "status": "OK",
  "data": {
    "IdempotencyId": "idempotencyId",
    "GivingTransactionIds": [
      "givingTransactionId1",
      "givingTransactionId2"
    ],
    "ReceivingTransactionIds": [
      "receivingTransactionId1",
      "receivingTransactionId2"
    ]
  }
}

{
  "code": 123,
  "errorCode": 123,
  "status": "<string>",
  "error": "<string>",
  "errorMessage": "<string>",
  "errorDetails": {}
}

Authorizations

X-EntityToken

string

header

required

This API requires an Entity Session Token, available from the Entity GetEntityToken method.

Body

application/json

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

DeleteEmptyStacks

boolean

required

Indicates whether stacks reduced to an amount of 0 during the request should be deleted from the inventory. (Default = false)

Amount

number

The amount to transfer .

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

GivingEntity

object

The entity the request is transferring from. Set to the caller by default.

Show child attributes

GivingETag

string

ETags are used for concurrency checking when updating resources (before transferring from). More information about using ETags can be found here: https://learn.microsoft.com/en-us/gaming/playfab/features/economy-v2/catalog/etags

GivingItem

object

The inventory item the request is transferring from.

Show child attributes

IdempotencyId

string

The idempotency id for the request.

NewStackValues

object

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

Show child attributes

ReceivingCollectionId

string

The inventory collection id the request is transferring to. (Default="default")

ReceivingEntity

object

The entity the request is transferring to. Set to the caller by default.

Show child attributes

ReceivingItem

object

The inventory item the request is transferring to.

Show child attributes

Response

code

integer

The Http status code. If X-ReportErrorAsSuccess header is set to true, this will report the actual http error code.

status

string

The Http status code as a string.

data

object

Show child attributes

Example:

{
  "IdempotencyId": "idempotencyId",
  "GivingTransactionIds": [
    "givingTransactionId1",
    "givingTransactionId2"
  ],
  "ReceivingTransactionIds": [
    "receivingTransactionId1",
    "receivingTransactionId2"
  ]
}

Last modified on October 1, 2026

⌘I

Transfer Inventory Items

curl --request POST \
  --url https://{titleId}.playfabapi.com/Inventory/TransferInventoryItems \
  --header 'Content-Type: application/json' \
  --header 'X-EntityToken: <api-key>' \
  --data '
{
  "GivingItem": {
    "Id": "11111111-1111-1111-1111-111111111111"
  },
  "ReceivingItem": {
    "Id": "11111111-1111-1111-1111-111111111111"
  },
  "Amount": 1,
  "GivingCollectionId": "default",
  "ReceivingCollectionId": "backpack"
}
'

import requests

url = "https://{titleId}.playfabapi.com/Inventory/TransferInventoryItems"

payload = {
    "GivingItem": { "Id": "11111111-1111-1111-1111-111111111111" },
    "ReceivingItem": { "Id": "11111111-1111-1111-1111-111111111111" },
    "Amount": 1,
    "GivingCollectionId": "default",
    "ReceivingCollectionId": "backpack"
}
headers = {
    "X-EntityToken": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-EntityToken': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    GivingItem: {Id: '11111111-1111-1111-1111-111111111111'},
    ReceivingItem: {Id: '11111111-1111-1111-1111-111111111111'},
    Amount: 1,
    GivingCollectionId: 'default',
    ReceivingCollectionId: 'backpack'
  })
};

fetch('https://{titleId}.playfabapi.com/Inventory/TransferInventoryItems', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{titleId}.playfabapi.com/Inventory/TransferInventoryItems",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'GivingItem' => [
        'Id' => '11111111-1111-1111-1111-111111111111'
    ],
    'ReceivingItem' => [
        'Id' => '11111111-1111-1111-1111-111111111111'
    ],
    'Amount' => 1,
    'GivingCollectionId' => 'default',
    'ReceivingCollectionId' => 'backpack'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-EntityToken: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{titleId}.playfabapi.com/Inventory/TransferInventoryItems"

	payload := strings.NewReader("{\n  \"GivingItem\": {\n    \"Id\": \"11111111-1111-1111-1111-111111111111\"\n  },\n  \"ReceivingItem\": {\n    \"Id\": \"11111111-1111-1111-1111-111111111111\"\n  },\n  \"Amount\": 1,\n  \"GivingCollectionId\": \"default\",\n  \"ReceivingCollectionId\": \"backpack\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-EntityToken", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{titleId}.playfabapi.com/Inventory/TransferInventoryItems")
  .header("X-EntityToken", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"GivingItem\": {\n    \"Id\": \"11111111-1111-1111-1111-111111111111\"\n  },\n  \"ReceivingItem\": {\n    \"Id\": \"11111111-1111-1111-1111-111111111111\"\n  },\n  \"Amount\": 1,\n  \"GivingCollectionId\": \"default\",\n  \"ReceivingCollectionId\": \"backpack\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{titleId}.playfabapi.com/Inventory/TransferInventoryItems")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-EntityToken"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"GivingItem\": {\n    \"Id\": \"11111111-1111-1111-1111-111111111111\"\n  },\n  \"ReceivingItem\": {\n    \"Id\": \"11111111-1111-1111-1111-111111111111\"\n  },\n  \"Amount\": 1,\n  \"GivingCollectionId\": \"default\",\n  \"ReceivingCollectionId\": \"backpack\"\n}"

response = http.request(request)
puts response.read_body

{
  "code": 200,
  "status": "OK",
  "data": {
    "IdempotencyId": "idempotencyId",
    "GivingTransactionIds": [
      "givingTransactionId1",
      "givingTransactionId2"
    ],
    "ReceivingTransactionIds": [
      "receivingTransactionId1",
      "receivingTransactionId2"
    ]
  }
}

{
  "code": 123,
  "errorCode": 123,
  "status": "<string>",
  "error": "<string>",
  "errorMessage": "<string>",
  "errorDetails": {}
}

PlayFab API

PlayFab REST API References

Transfer Inventory Items

Error codes

Authorizations

Body

Response