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.

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 selected a default currency in this case.

Pricing configuration restrictions:

• You can’t create an item without specifying its price in real or virtual currency.
• You can’t create an item with a zero value in price.

There are 3 types of virtual items:

• Consumable
• Nonconsumable
• Nonrenewing subscriptions

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 DLC, NO ADS option for mobile games, etc.

Nonrenewing subscriptions

A nonrenewing subscription 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: Battle Pass, Season Pass, temporary access to an in-game cosmetic item, item, or additional content.

See the nonrenewing subscriptions recipe for details.

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

Prerequisites

1. Sign up to Xsolla Publisher Account.
2. Open your project.

3. Go to Project settings > Integration settings and make sure that the Integrate Commerce API toggle is set to ON.

Integration flow

1. Configure virtual items and groups of virtual items.
2. 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 Ungrouped group.

To set up virtual items and groups of virtual items, you can:

• use functionality of Publisher Account
• use API calls

Configuration via Publisher Account

• Groups of virtual items
• Virtual items

To set up groups of virtual items:

1. Connect the Virtual Items module in Publisher Account.

2. Go to Store > Virtual Items and click Create a group.

3. Specify the following parameters:
   1. Group code.
   2. Group name.

4. Set the Show group in Store toggle to ON.
5. Click Create group.

To set up a virtual item:

1. Connect the Virtual Items module in Publisher Account.

2. Create an item.

3. For every item, specify:
   1. Image.
   2. SKU.
   3. One or several groups the item should belong to.
   4. Name.
   5. Description.
   6. Item property: consumable, nonconsumable, or nonrenewing subscription.
   7. Prices in real or virtual currencies.

4. Set the Show item in store toggle to ON.
5. Click Create an item.

Configuration via API calls

Use API calls from the Admin subsection of the Virtual Items & Currency group to set up virtual items.

Basic authorization is used for the API calls. Pass the Authorization:Basic <your_authorization_basic_key>, where <your_authorization_basic_key> parameter is the merchant ID:API key pair, encoded according to the Base64 standard. You can find merchant ID in Project settings > Webhooks in Publisher Account. You can find the API key in Company settings > API key in Publisher Account.

Use API calls from the Catalog subsection of the Virtual Items & Currency group to get the catalog of virtual items on the client side. These calls don’t require basic authorization.

Use the Get virtual items list API call to get the full list of items not divided into groups. To get the list of items from the definite group, pass the external_id parameter to the Get items list by specified group call.

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 Create item or Update item calls.

"regions": [{
     “id”: “123”
  }, {
     “id”: “456”
  }
]

To set up regional prices for virtual items, pass an array of objects with regional prices settings to the Create item or Update item calls.

"regional_prices": [{
     “region_id”: “123”,
     “country_iso”: “CHN”,
     “amount”: 40,
     “currency_iso”: “CNY”,
     “is_default”: true,
     “is_enabled”: true
  }
]