Player inventory
Inventory is a set of all items within the game that the user can buy, earn, or spend.
Xsolla Player Inventory allows partners to:
- Synchronize all purchases and premium rewards of the user on all platforms.
- Use Xsolla API to grant and revoke items and currency in the user’s inventory.
How it works
Player Inventory manages the user’s inventory by the user ID. User identification is implemented through Xsolla Login. If you configured your own identification system, you can use the Pay Station access token for client API methods.
To work with Player Inventory API methods, authentication must be configured.
The user’s inventory may include both the consumable and nonconsumable items. Consumable items can be purchased and added to the inventory several times and removed from it through the game client. Nonconsumable items can only be purchased and added to the inventory once. Canceling the purchase and removing it from the inventory are carried out through the game server.
The scheme above illustrates the following principle of operating with Player Inventory:
- Getting the inventory
- The user is identified in the game by their Xsolla Login account or your identification method.
- Your application (client) calls the Get user’s inventory method to get a list of purchases and user rewards and the Get user’s virtual balance method to get the balance of virtual currency.
- The Xsolla Inventory server returns information about purchases, rewards, or the balance currently owned by the user to your client.
- In-game purchase via Xsolla Store
- The user is identified in the game by their Xsolla Login account or your identification method.
- The user makes a purchase via Xsolla Store.
- The content purchase event is sent to the Xsolla Inventory server, and then the purchased items are automatically granted to the user’s inventory.
- In-app purchase via a third-party publishing platform (Steam, PlayStation, etc.)
- The user logs in to the game using the platform account.
- The user makes a purchase through the platform payment system.
- The game server calls the Grant items by purchase to users method to grant the purchase on the Xsolla Inventory server sending them a unique user ID within the game.
- The Xsolla Inventory server adds a purchase to the user’s inventory with the specified ID.
- Granting rewards to the user
- The user is identified in the game using their Xsolla Login account or your identification method.
- Your server calls the Grant items to users method to grant a reward, sending a unique user ID inside the game.
- The Xsolla Inventory server adds a reward to the user’s inventory with the specified ID.
- Inventory synchronization
- The user is identified in the game by their Xsolla Login account, your identification method, or a third-party platform account.
- The game server synchronizes user accounts if necessary.
- The game client calls the Get user’s inventory method to check which in-game purchases are available for use and sends a unique user ID.
- The Xsolla Inventory server returns a list of available items for the specified ID.
Integration flow
To enable Player Inventory:
- Set up Xsolla In-game Store.
- Set up authentication.
- Implement methods for inventory management.
Authentication setup
To provide security, the granting and revoking methods are called by the game server. It is necessary to implement basic access authentication for the methods mentioned above.
The methods for getting the user’s inventory and consuming items are called by the game client via SDK or API. Here are the possible authentication options:
- If you have Xsolla Login connected, use Xsolla Login JWT to authenticate requests.
- If you have set up your own identification system, use Pay Station access token to authenticate requests.
user.id
to the server-based granting and revoking items methods. It must be identical to the user.id
you use for Pay Station access token.Authentication via Xsolla Login
- Set up a Publisher Account project following the instructions.
- Implement the call of the authorization methods with the help of the JSON Web Token or OAuth 2.0 protocol.
If the user data is kept in the Xsolla data storage, implement the call of the following methods:
If the user data is kept in the PlayFab data storage, use the PlayFab recipe.
If the user data is kept on your side, use the Custom storage recipe.
Authentication via Pay Station access token
Authentication flow:
- Your application (client) sends the authentication request to your server.
- Your server sends the Merchant ID and API key to the Xsolla server and requests access_token.
- Xsolla server sends access_token to your server.
- Your server sends access_token to your client.
The returned access_token is used as an authorization token for authentication in the
Set up basic access authentication
The server commands for granting and revoking the items from the Xsolla API inventory use basic access authentication. All requests to API must contain the Authorization: Basic <your_authorization_basic_key>
header where <your_authorization_basic_key>
is the merchant ID:API key pair encoded according to the Base64 standard.
Go to Publisher Account to find these parameters:
- Merchant ID is shown:
- In the Project settings > Webhooks section.
- In the Company settings > Company section.
- In the URL in the browser address bar on any Publisher Account page. The URL has the following format:
https://publisher.xsolla.com/merchant ID/Publisher Account section
.
- API key is shown in Publisher Account only once when it is created and must be stored on your side. You can create a new key in the following section:
- Company settings > API keys
- Project settings > API keys
For more information about working with API keys, see the API reference.
Key recommendations:
- Save the generated API key on your side. You can view the API key in Publisher Account only once when it is created.
- Keep your API key a secret. It provides access to your personal account and your projects in Publisher Account.
- The API key must be stored on your server and never in binaries or on the frontend.
- http
- curl
- php
- C#
- python
- ruby
- java
- js
POST https://store.xsolla.com/api/v2/project/{project_id}/inventory/reward
Headers:
Authorization: Basic <your_authorization_basic_key>
curl --request POST \
--url 'https://store.xsolla.com/api/v2/project/{project_id}/inventory/reward' \
--header 'authorization: Basic <your_authorization_basic_key>'
<?php
$uri = 'https://store.xsolla.com/api/v2/project/{project_id}/inventory/reward';
$auth = base64_encode('your_merchant_id:your_merchant_api_key');
$headers = [
'Authorization: Basic ' . $auth,
'Content-Type: application/json',
'Accept: application/json',
];
$request = curl_init($uri);
curl_setopt($request, CURLOPT_RETURNTRANSFER, true);
curl_setopt($request, CURLOPT_POST, true);
curl_setopt($request, CURLOPT_POSTFIELDS, []);
curl_setopt($request, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($request);
print_r($response);
var client = new RestClient("https://store.xsolla.com/api/v2/project/{project_id}/inventory/reward");
var request = new RestRequest(Method.POST);
request.AddHeader("authorization", "Basic <your_authorization_basic_key>");
IRestResponse response = client.Execute(request);
import http.client
conn = http.client.HTTPSConnection("api.xsolla.com")
headers = { 'authorization': "Basic <your_authorization_basic_key>" }
conn.request("POST", "https://store.xsolla.com/api/v2/project/{project_id}/inventory/reward", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
require 'uri'
require 'net/http'
url = URI("https://store.xsolla.com/api/v2/project/{project_id}/inventory/reward
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Get.new(url)
request["authorization"] = 'Basic <your_authorization_basic_key>'
response = http.request(request)
puts response.read_body
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://store.xsolla.com/api/v2/project/{project_id}/inventory/reward")
.post()
.addHeader("authorization", "Basic <your_authorization_basic_key>")
.build();
Response response = client.newCall(request).execute();
var data = null;
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://store.xsolla.com/api/v2/project/{project_id}/inventory/reward");
xhr.setRequestHeader("authorization", "Basic <your_authorization_basic_key>");
xhr.send(data);
Inventory management methods
Inventory management methods include the following groups of methods:
- Server methods:
- Client methods:
Grant items to users
Implement the Grant items to users API method to add the specified item to the user’s inventory or the virtual currency to their balance.
Request:
- php
<?php
$uri = 'https://store.xsolla.com/api/v2/project/44056/inventory/reward';
$body = '
[
{
"user": {
"id": "0125760a-6810-11e9-84c0-42010aa80029"
},
"comment": "Quest completed",
"platform": "xsolla",
"items": [
{
"sku": "boots_1",
"quantity": 5
},
{
"sku": "crystal_pack_1",
"quantity": 3
}
]
},
{
"user": {
"id": "a7d10a4e-3f68-43cc-a6b2-893d2c68fd14"
},
"comment": "Daily reward",
"platform": "xsolla",
"items": [
{
"sku": "helmet_1",
"quantity": 2
},
{
"sku": "minigun_1",
"quantity": 3
}
]
}
]';
$auth = base64_encode('44056:your_merchant_api_key');
$headers = [
'Authorization: Basic ' . $auth,
'Content-type: application/json'
];
$request = curl_init($uri);
curl_setopt($request, CURLOPT_RETURNTRANSFER, true);
curl_setopt($request, CURLOPT_POSTFIELDS, $body);
curl_setopt($request, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($request);
Response:
- php
{
"count": 2,
"operations": [
{
"user_id": "0125760a-6810-11e9-84c0-42010aa80029",
"platform": "xsolla",
"comment": "Quest completed",
"items": [
{
"sku": "boots_1",
"quantity": 5
},
{
"sku": "crystal_pack_1",
"quantity": 3
}
]
},
{
"user_id": "a7d10a4e-3f68-43cc-a6b2-893d2c68fd14",
"platform": "xsolla",
"comment": "Daily reward",
"items": [
{
"sku": "helmet_1",
"quantity": 2
},
{
"sku": "minigun_1",
"quantity": 3
}
]
}
]
}
Revoke inventory items
Implement the Revoke inventory items API method to revoke the specified item from the user’s inventory or the virtual currency from their balance.
Request:
- php
<?php
$uri = 'https://store.xsolla.com/api/v2/project/44056/inventory/revoke';
$body = '
[
{
"user": {
"id": "0125760a-6810-11e9-84c0-42010aa80029"
},
"comment": "Remove from inventory",
"items": [
{
"sku": "boots_1",
"quantity": 5
},
{
"sku": "crystal_pack_1",
"quantity": 3
}
]
},
{
"user": {
"id": "a7d10a4e-3f68-43cc-a6b2-893d2c68fd14"
},
"comment": "Cheater",
"items": [
{
"sku": "helmet_1",
"quantity": 2
},
{
"sku": "minigun_1",
"quantity": 3
}
]
}
]';
$auth = base64_encode('44056:your_merchant_api_key');
$headers = [
'Authorization: Basic ' . $auth,
'Content-type: application/json'
];
$request = curl_init($uri);
curl_setopt($request, CURLOPT_RETURNTRANSFER, true);
curl_setopt($request, CURLOPT_POSTFIELDS, $body);
curl_setopt($request, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($request);
print_r($response);
Response:
- php
{
"count": 2,
"operations": [
{
"user_id": "0125760a-6810-11e9-84c0-42010aa80029",
"platform": "xsolla",
"comment": "Remove from inventory",
"items": [
{
"sku": "boots_1",
"quantity": 5
},
{
"sku": "crystal_pack_1",
"quantity": 3
}
]
},
{
"user_id": "a7d10a4e-3f68-43cc-a6b2-893d2c68fd14",
"platform": "xsolla",
"comment": "Cheater",
"items": [
{
"sku": "helmet_1",
"quantity": 2
},
{
"sku": "minigun_1",
"quantity": 3
}
]
}
]
}
Grant items by purchase to users
Implement the Grant items by purchase to users API method to add the item to the user’s inventory when the purchase is made on the third-party platform.
Request:
- php
<?php
$uri = 'https://store.xsolla.com/api/v2/project/44056/inventory/purchase';
$body = '
[
{
"user": {
"id": "0125760a-6810-11e9-84c0-42010aa80029"
},
"comment": "Purchase in App Store",
"platform": "app_store_ios",
"purchase": {
"amount": "3.99",
"currency": "USD",
"external_purchase_id": "MS6TGW7023",
"external_purchase_date": "2020-01-25T05:00:00+05:00"
},
"items": [
{
"sku": "boots_1",
"quantity": 5
},
{
"sku": "crystal_pack_1",
"quantity": 3
}
]
},
{
"user": {
"id": "a7d10a4e-3f68-43cc-a6b2-893d2c68fd14"
},
"comment": "Purchase in Google Play",
"platform": "google_play",
"purchase": {
"amount": "1.99",
"currency": "EUR",
"external_purchase_id": "GPA.3357-9348-5932-89841",
"external_purchase_date": "2020-02-14T05:00:00+05:00"
},
"items": [
{
"sku": "helmet_1",
"quantity": 2
},
{
"sku": "minigun_1",
"quantity": 3
}
]
}
]';
$auth = base64_encode('44056:your_merchant_api_key');
$headers = [
'Authorization: Basic ' . $auth,
'Content-type: application/json'
];
$request = curl_init($uri);
curl_setopt($request, CURLOPT_RETURNTRANSFER, true);
curl_setopt($request, CURLOPT_POSTFIELDS, $body);
curl_setopt($request, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($request);
print_r($response);
Response:
- php
{
"count": 2,
"operations": [
{
"user_id": "0125760a-6810-11e9-84c0-42010aa80029",
"platform": "app_store_ios",
"comment": "Purchase in App Store",
"items": [
{
"sku": "boots_1",
"quantity": 5
},
{
"sku": "crystal_pack_1",
"quantity": 3
}
],
"order_id": 4125,
"external_purchase_id": "MS6TGW7023",
"external_purchase_date": "2020-01-25T05:00:00+05:00",
"amount": "3.99",
"currency": "USD"
},
{
"user_id": "a7d10a4e-3f68-43cc-a6b2-893d2c68fd14",
"platform": "google_play",
"comment": "Purchase in Google Play",
"items": [
{
"sku": "helmet_1",
"quantity": 2
},
{
"sku": "minigun_1",
"quantity": 3
}
],
"order_id": 4126,
"external_purchase_id": "GPA.3357-9348-5932-89841",
"external_purchase_date": "2020-02-14T05:00:00+05:00",
"amount": "1.99",
"currency": "EUR"
}
]
}
Get user’s inventory
Implement the Get user’s inventory API method to get the list of items added to the user’s inventory after the purchase.
Request:
- js
var data = null;
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
}
});
xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/user/inventory/items");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");
xhr.send(data);
Response:
- js
{
"items": [
{
"description": "Conquer your foes with vindication using the Basic Blaster! ",
"image_url": "https://cdn.xsolla.net/img/misc/images/0c59a7698d4f66c1008b27ee752089b7.png",
"instance_id": null,
"long_description": "Conquer your foes with vindication using the Basic Blaster! Conquer your foes with vindication using the Basic Blaster! ",
"name": "Xsolla Basic Blaster 1",
"quantity": 22,
"sku": "gun_1",
"type": "virtual_good"
},
{
"description": "Protect your noggin' with style",
"image_url": "https://cdn.xsolla.net/img/misc/images/b79342cdf24f0f8557b63c87e8326e62.png",
"instance_id": null,
"long_description": "merchant_virtual_items_virtual_item_long_description_159429",
"name": "Xsolla Helmet",
"quantity": 18,
"sku": "helmet_1",
"type": "virtual_good"
}
]
}
Get user’s virtual balance
Implement the Get user’s virtual balance API method to get the information about the current user virtual currency balance.
Request:
- js
var data = null;
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
}
});
xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/user/virtual_currency_balance");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");
xhr.send(data);
Response:
- js
{
"items": [
{
"amount": 683,
"description": "Main in-game currency",
"image_url": "https://cdn3.xsolla.com/img/misc/images/91df536af4616519f639664854c13d75.png",
"name": "Crystals",
"sku": "crystal",
"type": "virtual_currency"
},
{
"amount": 450,
"description": "Money for in-store purchases",
"image_url": "https://cdn3.xsolla.com/img/misc/images/fda67a3feedaa706b4e4ae05a9edd6ab.png",
"name": "Gold",
"sku": "gold",
"type": "virtual_currency"
}
]
}
Consume item
Implement the Consume item API method to consume the item from the user’s inventory.
Request:
- js
let data = JSON.stringify({
"sku": "gun_1",
"quantity": 1,
"instance_id": null
});
let xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://store.xsolla.com/api/v2/project/44056/user/inventory/item/consume");
xhr.setRequestHeader("content-type", "application/json");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");
xhr.send(data);
Errors list
User or user’s inventory management errors:
Code | Description | Action |
---|---|---|
0401-5002 | Wrong data for adding the item to user’s inventory. | The item_id must be specified and instance_id or quantity must have the null value. |
0401-5003 | User ID not specified. | Check the presence of user ID in the request. |
0401-5004 | Items not found in user’s inventory. | Make sure that the item is in the inventory. The inventory status is checked via the Get user’s inventory method. |
0401-5006 | Not enough virtual currency for purchasing. | - |
0401-5007 | Attempt to consume nonconsumable item. | - |
0401-5008 | User not found. | - |
0401-5009 | When granting third-party platform purchase, purchase is not passed. | - |
Item management errors:
Code | Description | Action |
---|---|---|
0401-4001 | Item not found by criteria. | Check the list of items by calling the Get user’s inventory method. |
Code | Description | Action |
---|---|---|
0401-1101 | Service not available (wrong address, connection issues). | Check the system status at status.xsolla.com; contact Xsolla Customer Support team, your Customer Success Manager or email to csm@xsolla.com. |
0401-1102 | Wrong request entry data. | Check the API specification. |
0401-1016 | Wrong encoding of one of request parameters. | Check the request contents. |
0401-1019 | Method not supported. | Check the request. Supported methods are found in the response. |
0401-1020 | Authorization error when using merchant’s key hash. | Check API key. |
Was this article helpful?
Rate this page
Don’t want to answer
Thank you for your feedback!
Found a typo or other text error? Select the text and press Ctrl+Enter.