Virtual items

How it works

Virtual items are in-game items that users can purchase for real or virtual currency or receive as a bonus. They have no physical form and are used only within the game. Examples of virtual items include skins, potions, weapons, and other elements that affect gameplay or a character’s appearance.

Main features:

• Flexible pricing configuration:
  • Setting a price for a single item in real and/or virtual currency.
  • Creating free items.
• Automatic detection of the user’s country and currency.
• Availability configuration:
  • Restricting item sales in specific region.
  • Limiting the number of items available for purchase.
  • Limiting the display time of items in the store.
  • Configuring items that are not available for purchase. An item can be hidden from the catalog but still be available as part of a bundle or as a bonus for another item.

How to set up

2. Click Create manually and select Virtual item from the drop-down list.

3. In the General settings section, specify the following:
   • SKU
   • One or several groups the item should belong to (optional)
   • Name
   • Short description
   • Extended description — to add it, turn on the corresponding toggle (optional)

4. In the Media section, upload one or more images or videos (optional) — from your device or via a link. In the store created with the Xsolla site editor, all item cards display the file marked as Main, while the remaining files are available only in item cards with a media gallery. The file marked as Main is also returned in the responses of the catalog retrieval API calls.

5. In the Price settings section, set prices or create a free item:
   • To set a price, select Paid item, turn on the Pricing in real currency and/or Pricing in virtual currency toggle, and specify the price. If needed, configure regional prices.
   • To create a free item, select Free item.

6. To limit the number of items available for purchase:
   1. Turn on the toggle in the Limits section and specify the quantity.
   2. Configure the limit reset frequency. To do this, select a period from the drop-down list:
      • Daily.
      • Weekly.
      • Monthly.
      • Custom interval. The interval is calculated from the item’s display start date in the store.
      • No regular refresh.
   3. Set up the reset schedule by specifying the parameters that correspond to the selected period.

7. To configure a display time limit for the item (optional):

   1. Turn on the toggle in the Add specific display period section.
   2. Specify the time zone and the beginning and the end of the period.

   To leave the end of the item’s display period unspecified, turn on the No end date toggle.

8. Configure attributes using one of the following options (optional):
   1. Add attributes and their values in JSON format.
   2. Manually create attributes and their values, and link them to items.

9. If the paid item will be used in any mechanics with a random reward (e.g., loot boxes or gacha), enable the Mark as paid randomized reward toggle.

10. Click Create.

11. In the window that opens, select the item status and click Continue.

The created item will appear in the All items section.

Set up via API

To set up virtual items, you can use the calls from the Admin subsection in the Virtual items and currency group.

Display virtual items in store

The display of virtual items depends on how the catalog is implemented — through the site editor or via API.

Display via site editor

To display a virtual item on your website:

1. Create a virtual item.

2. In your project in Publisher Account, go to the Storefronts > Websites section.

3. In the pane of the desired site, click Open Site Builder.

2. In your project in the account for mobile games, go to the Web Shop section.

3. Click the pane of the desired site.

4. If your site includes multiple pages, select the one you need:

   1. Click the current page title at the top of the editor.
   2. Select the necessary page from the drop-down list.

5. In the Store block section, select Virtual items in the Item type field and select the item group you want to sell on the website in the Item group field.

6. Set an item card layout.

7. After making all necessary changes and preparing your website for launch:

   1. In the upper-right corner of the site editor, click Publish.
   2. Check the boxes next to the pages you want to publish.
   3. Click Publish.

Once the site is published, a section with a virtual item group will become available. If no items are displayed, check that their status is set to Available and that no time-based display limit is active.

Get virtual item information via API

To retrieve the virtual items catalog on the client side, use the methods from the Catalog subsection of the Virtual items and currency method group. Authorization is not required to use these methods.

Grant virtual items to users

Depending on the item type and integration settings, the virtual item is granted to the user in one of the following ways:

• If you’ve integrated PlayFab, virtual currency and items are granted to the user’s PlayFab inventory automatically.
• If you use a custom delivery system, all virtual items and currency are granted on your side. We recommend setting up a webhook handler to receive order data on your backend. The necessary data is included in the Successful payment for order webhook.

Refer to the Set up order status tracking section for more details on this and other methods of retrieving purchase data.

Useful links