Virtual items
How it works
Virtual items are in-game content that you can sell for real and virtual currency.
Main features:
- Set up prices in real and virtual currency.
- Configure catalog with several levels.
- Automatically determine the user’s currency and country.
- Limiting the number of items available for purchase.
- Limiting the display time for items in the store.
- Free items.
Pricing configuration features:
- One item can have the price both in real and virtual currencies.
- You can set up prices in several real or virtual currencies. Make sure you select a default currency in this case.
- You can create an item without specifying its price in real or virtual currency. If such an item is displayed in the store, it will be available to users for free.
Pricing configuration restrictions:
- You can’t create an item with a zero price value.
There are 3 types of virtual items:
Consumable virtual items
A consumable item is an item in the inventory that you can have in large quantities and purchase several times. Its quantity is decreased when users consume it.
Main features:
- Replenish the stock of items in the inventory.
- Store many instances of the same item in the user inventory.
- Can be consumed from the client side.
Example: Grenades, bullets, etc.
Nonconsumable virtual items
A nonconsumable item is an item in the inventory that can be accrued or purchased only once.
Main features:
- Users can have only one unit of this item in the inventory.
- Can’t be removed from the inventory by being consumed on the client side. You can withdraw it only via a server method.
Example: Access to a location, status, cosmetics, preinstalled
Time-limited items
A time-limited item is a one-time purchase. The user needs to buy it again when it expires.
Main features:
- Becomes inactive when it expires.
- The user buys this subscription again to activate it.
Example:
See the time-limited items recipe for details.
Limiting number of items available for purchase
You can limit the purchase of items. For example, you can limit:
- the number of items per user
- welcome items that are only available for purchase once
If the user has reached the specified limit, the item will not be displayed in the catalog.
You can display the maximum available number of items and the remaining number of items that is available to the user.
To set a purchase limit when creating an item in Publisher Account, switch the Limit number of times one user can buy this item toggle to On and specify the number of times the item can be bought.
You can use the methods of the Catalog subsection from the Virtual Items & Currency method group to get information about items.
In the response, you will receive the following information in addition to information about the virtual item:
- the maximum number of items a user can buy
- the remaining number of items available for the user to purchase
You can read more about how to set up or update restrictions in the Limits for user instructions.
For unauthorized users, the maximum number of items they can buy is always displayed. To display the remaining number of items to the user (subject to the current limit), pass user authorization data when you request the item catalog using the methods of the Catalog subsection from the Virtual Items & Currency method group.
To correctly display the number of items that are available to the user, you need to configure authentication.
- json
{
"items": [
{
"sku": "big_rocket",
"name": "Big Rocket",
"groups": [
{
"external_id": "accessory",
"name": "Accessory"
}
],
"attributes": [
{
"external_id": "stack_size",
"name": "Stack size",
"values": [
{
"external_id": "size_e3364991f92e751689a68b96598a5a5a84010b85",
"value": "5"
}
]
}
],
"type": "virtual_good",
"description": "Big Rocket - description",
"image_url": "https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png",
"is_free": false,
"price": {
"amount": "100.99",
"amount_without_discount": "100.99",
"currency": "USD"
},
"virtual_prices": [
{
"amount": 100,
"sku": "vc_test",
"is_default": true,
"amount_without_discount": 100,
"image_url": "http://image.png",
"name": "SHOTGUN FOR TRUE RAIDERS",
"type": "virtual_currency",
"description": "description"
}
],
"can_be_bought": true,
"inventory_options": {
"consumable": {
"usages_count": 1
},
"expiration_period": {
"type": "day",
"value": 1
}
},
"virtual_item_type": "non_renewing_subscription",
"limits": {
"per_user": {
"total": 5,
"available": 5
},
"per_item": null
},
}
Xsolla ensures the limits are not exceeded and prevents users from purchasing more items than the set limit.
When opening the payment interface and paying for an item, all unpaid orders with this item become invalid.
Example: the user can open the payment form for an item with a purchase restriction in several browser tabs until the item has been purchased. This automatically results in the creation of multiple orders for the same item. After purchasing an item in one tab, Xsolla will void all unpaid orders with the same item.
Limiting the display time for items in the store
You can set the display period for an item in the store to:- maintain the relevance of the catalog at a given time, for example, during holiday sales
- create an item in advance without displaying it in the catalog
- motivate users to buy items by displaying a timer next to the item
periods[0].date_from
with the date and time of the beginning of item display period inYYYY-MM-DDThh:mm:ss±TMZ
format, whereTMZ
is the time zone indicator inhh:mm
GMT formatperiods[0].date_until
with the date and time of the end of the item display period inYYYY-MM-DDThh:mm:ss±TMZ
format, whereTMZ
is the time zone indicator inhh:mm
GMT format. To not indicate the end of an item’s display period, passnull
You can set up multiple periods for displaying an item in the store. To do this, in the Create virtual item or Update virtual item method, pass an array of objects with the start and end dates of all periods.
Example:
"periods": [
{
"date_from": "2022-06-10T14:00:00+03:00",
"date_until": "2022-06-30T14:00:00+03:00"
},
{
"date_from": "2022-07-10T14:00:00+03:00",
"date_until": "2022-07-30T14:00:00+03:00"
},
{
"date_from": "2022-08-10T14:00:00+03:00",
"date_until": "2022-08-30T14:00:00+03:00"
}
]
Who can use it
- Partners who want to set up game economy or monetization by adding virtual currency to the game and selling virtual items for this currency.
- For partners who integrated In-Game Store and want to set up a new type of product – virtual items.
How to get it
Integration flow
- Configure virtual items and groups of virtual items.
- Configure regional restrictions and regional prices.
Configure virtual items and groups of virtual items
To set up virtual items, you need to configure virtual items groups. Groups allow you to have a multilevel catalog. Items that don’t have a specified group are added to the
To set up virtual items and groups of virtual items, you can:
Configuration via Publisher Account
Configuration via API calls
Use API calls from theBasic authorization is used for API calls. Pass the Authorization:Basic <your_authorization_basic_key>
, 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 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.
If an API call you need does not contain the project_id
path parameter, use the API key that is valid in all the company’s projects to set up authorization.
Use API calls from the
Use the external_id
parameter to the
Configure regional restrictions and regional prices
To set up regional restrictions for virtual items, pass an array of objects with identifiers of regions where the item will be available to the- http
"regions": [{
“id”: “123”
}, {
“id”: “456”
}
]
To set up regional prices for virtual items, pass an array of objects with regional prices settings to the
- http
"regional_prices": [{
“region_id”: “123”,
“country_iso”: “CHN”,
“amount”: 40,
“currency_iso”: “CNY”,
“is_default”: true,
“is_enabled”: true
}
]
Found a typo or other text error? Select the text and press Ctrl+Enter.