Virtual items

How it works

Virtual items are in-game content that you can sell for real and virtual currency.

Main features:

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 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.

Note

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.

Response example:
Copy
Full screen
Small screen

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

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
Note
When you create a catalog interface using Site Builder, the timer is displayed automatically. When you create a catalog in your own interface, you need to implement the timer.
To set a time limit for displaying an item in the store via Publisher Account, select Time period and specify the time zone, the beginning, and end of the period. To not indicate the end of the item display period, check the No end date box.
Note
After creating a virtual item, virtual currency, or virtual currency package, you can set statuses for the item to determine whether it is available, unavailable, or partially available.
To set a time limit for displaying an item in the store via API, pass the following parameters in the Create virtual item or Update virtual item API call:
  • 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:

Copy
Full screen
Small screen
    "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:

    Configuration via Publisher Account

    Configuration via API calls

    Use API calls from the Admin subsection of the Virtual Items & Currency group to set up virtual items.
    Notice
    Methods from the Admin subsection aren’t created for building a catalog in the store on the frontend side. You should use them for landing pages, web stores, and in-game logics.

    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 Project settings > Webhooks section.
      • 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
    Notice

    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.

    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.
    Copy
    Full screen
    Small screen
    "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.

    Copy
    Full screen
    Small screen
    "regional_prices": [{
         “region_id”: “123”,
         “country_iso”: “CHN”,
         “amount”: 40,
         “currency_iso”: “CNY”,
         “is_default”: true,
         “is_enabled”: true
      }
    ]
    
    Note
    You should configure regions in the project in advance. Contact your Customer Success Manager or email to csm@xsolla.com to do this.
    Was this article helpful?
    Thank you!
    Is there anything we can improve? Message
    We’re sorry to hear that
    Please explain why this article wasn’t helpful to you. Message
    Thank you for your feedback!
    We’ll review your message and use it to help us improve your experience.
    Rate this page
    Rate this page
    Is there anything we can improve?

    Don’t want to answer

    Thank you for your feedback!
    Last updated: October 10, 2023

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

    Report a problem
    We always review our content. Your feedback helps us improve it.
    Provide an email so we can follow up
    Thank you for your feedback!