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

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

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.

{
  "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
      },
}

Limiting the display time for items in the store

• 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 in YYYY-MM-DDThh:mm:ss±TMZ format, where TMZ is the time zone indicator in hh:mm GMT format

• periods[0].date_until with the date and time of the end of the item display period in YYYY-MM-DDThh:mm:ss±TMZ format, where TMZ is the time zone indicator in hh:mm GMT format. To not indicate the end of an item’s display period, pass null

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

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

Configuration via API calls

Basic 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

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

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

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