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.
Who can use it
- Partners who have integrated In-Game Store 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 your Xsolla Publisher Account.
- Go to Projects and click on the Create project button.
- Add Project name and click Create.
- Connect Store to your project.
- Connect the Virtual Items module.
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 getting time-limited items in an inventory.
- 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
- 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/items/virtual_items?locale=en");
xhr.send(data);
//RESPONSE
"items": [
{
"attributes": [],
"description": "Conquer your foes with vindication using the Basic Blaster! ",
"groups": [
"all",
"featured",
"Xsolla",
"weapons"
],
"image_url": "https://cdn.xsolla.net/img/misc/images/0c59a7698d4f66c1008b27ee752089b7.png",
"is_free": false,
"name": "Xsolla Basic Blaster 1",
"order": 1,
"price": {
"amount": "0.9950000000000000",
"amount_without_discount": "1.9900000000000000",
"currency": "USD"
},
"sku": "gun_1",
"type": "virtual_good"
Getting time-limited items in inventory
Use the
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 ID or Get current user’s cart API method for purchasing virtual items. Cart ID will be used to add/remove items.
Example
- 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/cart/custom_id?locale=en¤cy=USD");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");
xhr.send(data);
//RESPONSE
{
"cart_id": "custom_id",
"is_free": true,
"items": [],
"price": null
}
Create order with all items
- Implement one of the API methods:
- Create order with all items from particular cart if you got the cart by ID.
- 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
, whereACCESS_TOKEN
is the token received when the order was created. - To test the payment process:
- Use the following URL:
https://sandbox-secure.xsolla.com/paystation3/?access_token=ACCESS_TOKEN
. - Set the sandbox parameter to true in the request.
- Use the list of bank cards for testing.
- Use the following URL:
Example
- js
var data = JSON.stringify({
"currency": "USD",
"locale": "en",
"sandbox": false
});
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/44056/payment/cart/custom_id");
xhr.setRequestHeader("content-type", "application/json");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");
xhr.send(data);
//RESPONSE
{
"order_id": 641,
"token": "f4puMEFFDZcx9nv5HoNHIkPe9qghvBQo"
}
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
Example
- 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/order/656");
xhr.setRequestHeader("authorization", "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE5NjIyMzQwNDgsImlzcyI6Imh0dHBzOi8vbG9naW4ueHNvbGxhLmNvbSIsImlhdCI6MTU2MjE0NzY0OCwidXNlcm5hbWUiOiJ4c29sbGEiLCJ4c29sbGFfbG9naW5fYWNjZXNzX2tleSI6IjA2SWF2ZHpDeEVHbm5aMTlpLUc5TmMxVWFfTWFZOXhTR3ZEVEY4OFE3RnMiLCJzdWIiOiJkMzQyZGFkMi05ZDU5LTExZTktYTM4NC00MjAxMGFhODAwM2YiLCJlbWFpbCI6InN1cHBvcnRAeHNvbGxhLmNvbSIsInR5cGUiOiJ4c29sbGFfbG9naW4iLCJ4c29sbGFfbG9naW5fcHJvamVjdF9pZCI6ImU2ZGZhYWM2LTc4YTgtMTFlOS05MjQ0LTQyMDEwYWE4MDAwNCIsInB1Ymxpc2hlcl9pZCI6MTU5MjR9.GCrW42OguZbLZTaoixCZgAeNLGH2xCeJHxl8u8Xn2aI");
xhr.send(data);
//RESPONSE
{
"content": {
"is_free": false,
"items": [
{
"is_free": false,
"price": {
"amount": "0.9950",
"amount_without_discount": "1.9900",
"currency": "USD"
},
"quantity": 123,
"sku": "gun_1"
}
],
"price": {
"amount": "122.3850",
"amount_without_discount": "122.3850",
"currency": "USD"
}
},
"order_id": 656,
"status": "new"
}
Server-side time-limited items management
Granting
The game server can grant the time-limited item to users via the granting method.
The time-limited item expiration time will be calculated in the same way as during the time-limited item purchase.
Revoking
The game server can revoke the item from the user via the revoking method. Revoking the item means that it will be completely deleted from the user inventory.
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.