Inventory. Time-limited items

How it works

Time-limited item is a premium bonus which is a one-time purchase. Therefore, the user needs to buy it again when it expires.

Main features:

The time-limited item can be sold for an unlimited number of times.
When the user purchases the item again, the number of items in the inventory does not change, but the time before the item expires increases.
You can configure the item expiration time in your Publisher Account.

Restrictions:

You can manage the time-limited items from the game served side only.

If you want to limit the display time of an item in the store, use the Time limit for displaying items in store instructions.

Who can use it

Partners who have integrated Shop Builder and want to set up a new item type — time-limited items.
Partners who want to sell Season Pass, Battle Pass, or different types of items which give users advantage or additional content (e.g. in-game items or tasks) for a limited period of time.

How to get it

Prerequisites

If you have not integrated Xsolla Store yet, do the following:

Create a project in Publisher Account.
Go to the Items catalog > Virtual items section.

Integration flow

Create a group of items.
Create items:

When creating a new item, choose Time-limited items in the Item property menu.
Specify the expiration time.

Implement getting time-limited items in catalog.
Implement methods for purchasing time-limited items.

Getting time-limited items in catalog

Implement the Get virtual items list API method to show the full list of virtual items added to your store.

Example

Copy

Full screen

Small screen

 1var data = null;
 2
 3var xhr = new XMLHttpRequest();
 4xhr.withCredentials = true;
 5
 6xhr.addEventListener("readystatechange", function () {
 7  if (this.readyState === this.DONE) {
 8    console.log(this.responseText);
 9  }
10});
11
12xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/items/virtual_items?locale=en");
13
14xhr.send(data);
15
16//RESPONSE
17
18"items": [
19    {
20      "attributes": [],
21      "description": "Conquer your foes with vindication using the Basic Blaster! ",
22      "groups": [
23        "all",
24        "featured",
25        "Xsolla",
26        "weapons"
27      ],
28      "image_url": "https://cdn.xsolla.net/img/misc/images/0c59a7698d4f66c1008b27ee752089b7.png",
29      "is_free": false,
30      "name": "Xsolla Basic Blaster 1",
31      "order": 1,
32      "price": {
33        "amount": "0.9950000000000000",
34        "amount_without_discount": "1.9900000000000000",
35        "currency": "USD"
36      },
37      "sku": "gun_1",
38      "type": "virtual_good"

Purchasing time-limited items

After the first purchase the time-limited item is added to the inventory.

After the second and future purchases:

If the time-limited item is active, the item expiration time sums with the remaining time.
If the time-limited item is not active, the item expiration time is default.

Implement the following methods to purchase a time-limited items.

Get cart

Implement the Get cart by cart ID or Get current user’s cart API method for purchasing virtual items. Cart ID will be used to add/remove items.

Example

Copy

Full screen

Small screen

 1var data = null;
 2
 3var xhr = new XMLHttpRequest();
 4xhr.withCredentials = true;
 5
 6xhr.addEventListener("readystatechange", function () {
 7  if (this.readyState === this.DONE) {
 8    console.log(this.responseText);
 9  }
10});
11
12xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/cart/custom_id?locale=en&currency=USD");
13xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");
14
15xhr.send(data);
16
17//RESPONSE
18
19{
20  "cart_id": "custom_id",
21  "is_free": true,
22  "items": [],
23  "price": null
24}

To enable the quick items purchase (without creating a cart), use the Create order with specified item API method.

Create order with all items

Implement one of the API methods:
1. Create order with all items from particular cart if you got the cart by ID.
2. Create order with all items from current cart if you got the current cart.

The created order will receive a New order status.

To open the payment UI in a new window, use the following link: https://secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN, where ACCESS_TOKEN is the token received when the order was created.
To test the payment process:
1. Use the following URL: https://sandbox-secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN.
2. Set the sandbox parameter to true in the request.
3. Use the list of bank cards for testing.

Example

Copy

Full screen

Small screen

 1var data = JSON.stringify({
 2  "currency": "USD",
 3  "locale": "en",
 4  "sandbox": false
 5});
 6
 7var xhr = new XMLHttpRequest();
 8xhr.withCredentials = true;
 9
10xhr.addEventListener("readystatechange", function () {
11  if (this.readyState === this.DONE) {
12    console.log(this.responseText);
13  }
14});
15
16xhr.open("POST", "https://store.xsolla.com/api/v2/project/44056/payment/cart/custom_id");
17xhr.setRequestHeader("content-type", "application/json");
18xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");
19
20xhr.send(data);
21
22//RESPONSE  
23
24{
25  "order_id": 641,
26  "token": "f4puMEFFDZcx9nv5HoNHIkPe9qghvBQo"
27}

Get order

Implement the Get order API method to determine if the purchase has already been processed. The following order statuses are possible:

New — order is created but not paid
Paid — order is paid
Cancelled — order is cancelled
Done — order is paid and the item is added to the inventory

The status check should be carried out with a certain frequency, since a one-time check can occur earlier than the order is given the new status.

Example

Copy

Full screen

Small screen

 1var data = null;
 2
 3var xhr = new XMLHttpRequest();
 4xhr.withCredentials = true;
 5
 6xhr.addEventListener("readystatechange", function () {
 7  if (this.readyState === this.DONE) {
 8    console.log(this.responseText);
 9  }
10});
11
12xhr.open("GET", "https://store.xsolla.com/api/v2/project/44056/order/656");
13xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");
14
15xhr.send(data);
16
17//RESPONSE
18
19{
20  "content": {
21    "is_free": false,
22    "items": [
23      {
24        "is_free": false,
25        "price": {
26          "amount": "0.9950",
27          "amount_without_discount": "1.9900",
28          "currency": "USD"
29        },
30        "quantity": 123,
31        "sku": "gun_1"
32      }
33    ],
34    "price": {
35      "amount": "122.3850",
36      "amount_without_discount": "122.3850",
37      "currency": "USD"
38    }
39  },
40  "order_id": 656,
41  "status": "new"
42}

Thank you for your feedback!

We’ll review your message and use it to help us improve your experience.

Last updated: July 15, 2025

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

Contents

How it works
Who can use it
How to get it
Prerequisites
Integration flow
Getting time-limited items in catalog
Purchasing time-limited items

Your browser is not supported. Please try a different browser

Inventory. Time-limited items

How it works

Who can use it

How to get it

Prerequisites

Integration flow

Getting time-limited items in catalog

Purchasing time-limited items

Get cart

Create order with all items

Get order