Grant Items To Users
NOTE: This is a Legacy Economy API, and is in bugfix-only mode. All new Economy features are being developed only for version 2. Adds the specified items to the specified user inventories
Error codes
This operation may return the following PlayFab errors:
| Error | Code |
|---|---|
| AccountNotFound | 1001 |
| CatalogNotConfigured | 1218 |
| ProductDisabledForTitle | 1609 |
POST
/
Server
/
GrantItemsToUsers
Grant Items To Users
curl --request POST \
--url https://{titleId}.playfabapi.com/Server/GrantItemsToUsers \
--header 'Content-Type: application/json' \
--header 'X-SecretKey: <api-key>' \
--data '
{
"CatalogVersion": "5",
"ItemGrants": [
{
"PlayFabId": "20394883",
"ItemId": "shield_level_1",
"Annotation": "Entered Level 2"
},
{
"PlayFabId": "20394883",
"ItemId": "shield_level_2",
"Annotation": "Entered Level 2",
"Data": {
"Equipped": "True",
"Slot": "Head"
}
}
]
}
'import requests
url = "https://{titleId}.playfabapi.com/Server/GrantItemsToUsers"
payload = {
"CatalogVersion": "5",
"ItemGrants": [
{
"PlayFabId": "20394883",
"ItemId": "shield_level_1",
"Annotation": "Entered Level 2"
},
{
"PlayFabId": "20394883",
"ItemId": "shield_level_2",
"Annotation": "Entered Level 2",
"Data": {
"Equipped": "True",
"Slot": "Head"
}
}
]
}
headers = {
"X-SecretKey": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-SecretKey': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
CatalogVersion: '5',
ItemGrants: [
{PlayFabId: '20394883', ItemId: 'shield_level_1', Annotation: 'Entered Level 2'},
{
PlayFabId: '20394883',
ItemId: 'shield_level_2',
Annotation: 'Entered Level 2',
Data: {Equipped: 'True', Slot: 'Head'}
}
]
})
};
fetch('https://{titleId}.playfabapi.com/Server/GrantItemsToUsers', 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/Server/GrantItemsToUsers",
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([
'CatalogVersion' => '5',
'ItemGrants' => [
[
'PlayFabId' => '20394883',
'ItemId' => 'shield_level_1',
'Annotation' => 'Entered Level 2'
],
[
'PlayFabId' => '20394883',
'ItemId' => 'shield_level_2',
'Annotation' => 'Entered Level 2',
'Data' => [
'Equipped' => 'True',
'Slot' => 'Head'
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-SecretKey: <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/Server/GrantItemsToUsers"
payload := strings.NewReader("{\n \"CatalogVersion\": \"5\",\n \"ItemGrants\": [\n {\n \"PlayFabId\": \"20394883\",\n \"ItemId\": \"shield_level_1\",\n \"Annotation\": \"Entered Level 2\"\n },\n {\n \"PlayFabId\": \"20394883\",\n \"ItemId\": \"shield_level_2\",\n \"Annotation\": \"Entered Level 2\",\n \"Data\": {\n \"Equipped\": \"True\",\n \"Slot\": \"Head\"\n }\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-SecretKey", "<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/Server/GrantItemsToUsers")
.header("X-SecretKey", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"CatalogVersion\": \"5\",\n \"ItemGrants\": [\n {\n \"PlayFabId\": \"20394883\",\n \"ItemId\": \"shield_level_1\",\n \"Annotation\": \"Entered Level 2\"\n },\n {\n \"PlayFabId\": \"20394883\",\n \"ItemId\": \"shield_level_2\",\n \"Annotation\": \"Entered Level 2\",\n \"Data\": {\n \"Equipped\": \"True\",\n \"Slot\": \"Head\"\n }\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{titleId}.playfabapi.com/Server/GrantItemsToUsers")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-SecretKey"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"CatalogVersion\": \"5\",\n \"ItemGrants\": [\n {\n \"PlayFabId\": \"20394883\",\n \"ItemId\": \"shield_level_1\",\n \"Annotation\": \"Entered Level 2\"\n },\n {\n \"PlayFabId\": \"20394883\",\n \"ItemId\": \"shield_level_2\",\n \"Annotation\": \"Entered Level 2\",\n \"Data\": {\n \"Equipped\": \"True\",\n \"Slot\": \"Head\"\n }\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"code": 200,
"status": "OK",
"data": {
"ItemGrantResults": [
{
"PlayFabId": "20394883",
"Result": true,
"ItemId": "shield_level_1",
"ItemInstanceId": "133713371337",
"ItemClass": "shields",
"PurchaseDate": "2017-03-07T00:00:00",
"Expiration": "2018-10-01T00:00:00",
"RemainingUses": 10,
"Annotation": "Entered Level 2",
"CatalogVersion": "5",
"BundleParent": "crate block 1"
},
{
"PlayFabId": "20394883",
"Result": true,
"ItemId": "shield_level_2",
"ItemInstanceId": "133713371337",
"ItemClass": "shields",
"PurchaseDate": "2017-03-07T00:00:00",
"Expiration": "2018-10-01T00:00:00",
"RemainingUses": 10,
"Annotation": "Entered Level 2",
"CatalogVersion": "5",
"BundleParent": "crate block 1",
"CustomData": {
"Equipped": "True",
"Slot": "Head"
}
}
]
}
}{
"code": 123,
"errorCode": 123,
"status": "<string>",
"error": "<string>",
"errorMessage": "<string>",
"errorDetails": {}
}Authorizations
This API requires a title secret key, available to title admins, from PlayFab Game Manager.
Body
application/json
This function directly adds inventory items to user inventories. As a result of this operations, the user will not be charged any transaction fee, regardless of the inventory item catalog definition. Please note that the processing time for inventory grants and purchases increases fractionally the more items are in the inventory, and the more items are in the grant/purchase operation.
This function directly adds inventory items to user inventories. As a result of this operations, the user will not be charged any transaction fee, regardless of the inventory item catalog definition. Please note that the processing time for inventory grants and purchases increases fractionally the more items are in the inventory, and the more items are in the grant/purchase operation.
Array of items to grant and the users to whom the items are to be granted.
Show child attributes
Show child attributes
Catalog version from which items are to be granted.
The optional custom tags associated with the request (e.g. build number, external trace identifiers, etc.).
Response
Please note that the order of the items in the response may not match the order of items in the request.
The Http status code. If X-ReportErrorAsSuccess header is set to true, this will report the actual http error code.
The Http status code as a string.
Please note that the order of the items in the response may not match the order of items in the request.
Show child attributes
Show child attributes
Example:
{
"ItemGrantResults": [
{
"PlayFabId": "20394883",
"Result": true,
"ItemId": "shield_level_1",
"ItemInstanceId": "133713371337",
"ItemClass": "shields",
"PurchaseDate": "2017-03-07T00:00:00",
"Expiration": "2018-10-01T00:00:00",
"RemainingUses": 10,
"Annotation": "Entered Level 2",
"CatalogVersion": "5",
"BundleParent": "crate block 1"
},
{
"PlayFabId": "20394883",
"Result": true,
"ItemId": "shield_level_2",
"ItemInstanceId": "133713371337",
"ItemClass": "shields",
"PurchaseDate": "2017-03-07T00:00:00",
"Expiration": "2018-10-01T00:00:00",
"RemainingUses": 10,
"Annotation": "Entered Level 2",
"CatalogVersion": "5",
"BundleParent": "crate block 1",
"CustomData": { "Equipped": "True", "Slot": "Head" }
}
]
}
Last modified on October 1, 2026
Was this page helpful?
⌘I
Grant Items To Users
curl --request POST \
--url https://{titleId}.playfabapi.com/Server/GrantItemsToUsers \
--header 'Content-Type: application/json' \
--header 'X-SecretKey: <api-key>' \
--data '
{
"CatalogVersion": "5",
"ItemGrants": [
{
"PlayFabId": "20394883",
"ItemId": "shield_level_1",
"Annotation": "Entered Level 2"
},
{
"PlayFabId": "20394883",
"ItemId": "shield_level_2",
"Annotation": "Entered Level 2",
"Data": {
"Equipped": "True",
"Slot": "Head"
}
}
]
}
'import requests
url = "https://{titleId}.playfabapi.com/Server/GrantItemsToUsers"
payload = {
"CatalogVersion": "5",
"ItemGrants": [
{
"PlayFabId": "20394883",
"ItemId": "shield_level_1",
"Annotation": "Entered Level 2"
},
{
"PlayFabId": "20394883",
"ItemId": "shield_level_2",
"Annotation": "Entered Level 2",
"Data": {
"Equipped": "True",
"Slot": "Head"
}
}
]
}
headers = {
"X-SecretKey": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-SecretKey': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
CatalogVersion: '5',
ItemGrants: [
{PlayFabId: '20394883', ItemId: 'shield_level_1', Annotation: 'Entered Level 2'},
{
PlayFabId: '20394883',
ItemId: 'shield_level_2',
Annotation: 'Entered Level 2',
Data: {Equipped: 'True', Slot: 'Head'}
}
]
})
};
fetch('https://{titleId}.playfabapi.com/Server/GrantItemsToUsers', 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/Server/GrantItemsToUsers",
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([
'CatalogVersion' => '5',
'ItemGrants' => [
[
'PlayFabId' => '20394883',
'ItemId' => 'shield_level_1',
'Annotation' => 'Entered Level 2'
],
[
'PlayFabId' => '20394883',
'ItemId' => 'shield_level_2',
'Annotation' => 'Entered Level 2',
'Data' => [
'Equipped' => 'True',
'Slot' => 'Head'
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-SecretKey: <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/Server/GrantItemsToUsers"
payload := strings.NewReader("{\n \"CatalogVersion\": \"5\",\n \"ItemGrants\": [\n {\n \"PlayFabId\": \"20394883\",\n \"ItemId\": \"shield_level_1\",\n \"Annotation\": \"Entered Level 2\"\n },\n {\n \"PlayFabId\": \"20394883\",\n \"ItemId\": \"shield_level_2\",\n \"Annotation\": \"Entered Level 2\",\n \"Data\": {\n \"Equipped\": \"True\",\n \"Slot\": \"Head\"\n }\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-SecretKey", "<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/Server/GrantItemsToUsers")
.header("X-SecretKey", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"CatalogVersion\": \"5\",\n \"ItemGrants\": [\n {\n \"PlayFabId\": \"20394883\",\n \"ItemId\": \"shield_level_1\",\n \"Annotation\": \"Entered Level 2\"\n },\n {\n \"PlayFabId\": \"20394883\",\n \"ItemId\": \"shield_level_2\",\n \"Annotation\": \"Entered Level 2\",\n \"Data\": {\n \"Equipped\": \"True\",\n \"Slot\": \"Head\"\n }\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{titleId}.playfabapi.com/Server/GrantItemsToUsers")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-SecretKey"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"CatalogVersion\": \"5\",\n \"ItemGrants\": [\n {\n \"PlayFabId\": \"20394883\",\n \"ItemId\": \"shield_level_1\",\n \"Annotation\": \"Entered Level 2\"\n },\n {\n \"PlayFabId\": \"20394883\",\n \"ItemId\": \"shield_level_2\",\n \"Annotation\": \"Entered Level 2\",\n \"Data\": {\n \"Equipped\": \"True\",\n \"Slot\": \"Head\"\n }\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"code": 200,
"status": "OK",
"data": {
"ItemGrantResults": [
{
"PlayFabId": "20394883",
"Result": true,
"ItemId": "shield_level_1",
"ItemInstanceId": "133713371337",
"ItemClass": "shields",
"PurchaseDate": "2017-03-07T00:00:00",
"Expiration": "2018-10-01T00:00:00",
"RemainingUses": 10,
"Annotation": "Entered Level 2",
"CatalogVersion": "5",
"BundleParent": "crate block 1"
},
{
"PlayFabId": "20394883",
"Result": true,
"ItemId": "shield_level_2",
"ItemInstanceId": "133713371337",
"ItemClass": "shields",
"PurchaseDate": "2017-03-07T00:00:00",
"Expiration": "2018-10-01T00:00:00",
"RemainingUses": 10,
"Annotation": "Entered Level 2",
"CatalogVersion": "5",
"BundleParent": "crate block 1",
"CustomData": {
"Equipped": "True",
"Slot": "Head"
}
}
]
}
}{
"code": 123,
"errorCode": 123,
"status": "<string>",
"error": "<string>",
"errorMessage": "<string>",
"errorDetails": {}
}