Enable 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.

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 enable Player Inventory:

  1. Set up Xsolla In-game Store.
  2. Set up authentication.
  3. 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:

  1. If you have Xsolla Login connected, use Xsolla Login JWT to authenticate requests.
  2. If you have set up your own identification system, use Pay Station access token to authenticate requests.

Note
If you use your own user identification method, pass the 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

  1. Set up a Publisher Account project following the instructions.
  2. 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:

Note
To call the Xsolla API, you can use the ready-made SDK methods for game engines and platforms:

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:

  1. Your application (client) sends the authentication request to your server.
  2. Your server sends the Merchant ID and API key to the Xsolla server and requests access_token.
  3. Xsolla server sends access_token to your server.
  4. Your server sends access_token to your client.

The returned access_token is used as an authorization token for authentication in the Commerce API and building a store interface.

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 Xsolla Publisher Account to find values of the project_id and api_key parameters:

  • project_id: Project settings > Webhooks
  • api_key: Company settings > API key

Copy
Full screen
Small screen
http
  • 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:

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:

Copy
Full screen
Small screen
<?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:

Copy
Full screen
Small screen
{
    "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:

Copy
Full screen
Small screen
<?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:

Copy
Full screen
Small screen
{
    "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:

Copy
Full screen
Small screen
<?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:

Copy
Full screen
Small screen
{
    "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

Note
To call the Xsolla API, you can use the ready-made SDK methods for game engines and platforms:

Implement the Get user’s inventory API method to get the list of items added to the user’s inventory after the purchase.

Request:

Copy
Full screen
Small screen
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:

Copy
Full screen
Small screen
{
  "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

Note
To call the Xsolla API, you can use the ready-made SDK methods for game engines and platforms:

Implement the Get user’s virtual balance API method to get the information about the current user virtual currency balance.

Request:

Copy
Full screen
Small screen
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:

Copy
Full screen
Small screen
{
  "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

Note
To call the Xsolla API, you can use the ready-made SDK methods for game engines and platforms:

Implement the Consume item API method to consume the item from the user’s inventory.

Request:

Copy
Full screen
Small screen
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:

CodeDescriptionAction
0401-5002Wrong 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-5003User ID not specified.Check the presence of user ID in the request.
0401-5004Items 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-5006Not enough virtual currency for purchasing.-
0401-5007Attempt to consume nonconsumable item.-
0401-5008User not found.-
0401-5009When granting third-party platform purchase, purchase is not passed.-

Item management errors:

CodeDescriptionAction
0401-4001Item not found by criteria.Check the list of items by calling the Get user’s inventory method.

Commerce API management errors:

CodeDescriptionAction
0401-1101Service not available (wrong address, connection issues).Check the system status at status.xsolla.com; contact Xsolla Customer Support team or your Account Manager.
0401-1102Wrong request entry data.Check the API specification.
0401-1016Wrong encoding of one of request parameters.Check the request contents.
0401-1019Method not supported.Check the request. Supported methods are found in the response.
0401-1020Authorization error when using merchant’s key hash.Check API key.
Your progress
Thank you for your feedback!
Last updated: August 31, 2022

Found a typo or other text error? Select the text and press Ctrl+Enter.

Report a problem
We always review our content. Your feedback helps us improve it.
Provide an email so we can follow up
Thank you for your feedback!