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

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.

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 Account manager 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: November 25, 2022

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!