# Virtual items
## How it works {#general_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](/items-catalog/catalog-features/pricing-policy/#pricing_policy_country_determination).
* Availability configuration:
    * [Restricting item sales in specific region](/items-catalog/catalog-features/regional-restrictions/).
    * 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.

   **Audience: all other audiences**

   > [!NOTE]
   > Virtual items can be created [via Publisher Account](#general_how_to_set_up_via_pa), [via API calls](#general_how_to_set_up_via_api), or by importing a catalog.
   > This guide describes manual creation of virtual items and working with API calls. For detailed information about creating other item types, see the [Items catalog](/items-catalog/catalog-management/json-import/) section.

   **End of audience: all other audiences**

   **Audience: Free-to-play PC games, Premium PC games, Web games**

   > [!NOTE]
   > Virtual items can be created [via your account](#general_how_to_set_up_via_pa_account), [via API calls](#general_how_to_set_up_via_api), or by importing a catalog.
   > This guide describes manual creation of virtual items and working with API calls. For detailed information about creating other item types, see the [Items catalog](/items-catalog/catalog-management/json-import/) section.

   **End of audience: Free-to-play PC games, Premium PC games, Web games**

   **Audience: Mobile games**

   > [!NOTE]
   > Virtual items can be created [in the account for mobile games](#general_how_to_set_up_via_pa_mobile_games), [via API calls](#general_how_to_set_up_via_api), or by importing a catalog.
   > This guide describes manual creation of virtual items and working with API calls. For detailed information about creating other item types, see the [Items catalog](/items-catalog/catalog-management/json-import/) section.

   **End of audience: Mobile games**

## How to set up {#general_how_to_set_up}

**Audience: Publisher Account (legacy)**

### Set up in Publisher Account {#general_how_to_set_up_via_pa}

> [!NOTE]
> Before configuring items, it’s recommended to [create groups](/items-catalog/catalog-features/group-items/) to help you sort items and manage how they’re displayed in your store.

**End of audience: Publisher Account (legacy)**

**Audience: Free-to-play PC games, Premium PC games, Web games**

### Set up in your account {#general_how_to_set_up_via_pa}

> [!NOTE]
> Before configuring items, it’s recommended to [create groups](/items-catalog/catalog-features/group-items/) to help you sort items and manage how they’re displayed in your store.

**End of audience: Free-to-play PC games, Premium PC games, Web games**

**Audience: all other audiences**

1. Open your project in Publisher Account and go to the [Items catalog > All items > Virtual items](https://publisher.xsolla.com/0/projects/0/storefront/virtual-items) section.

   **End of audience: all other audiences**

   **Audience: Free-to-play PC games**

1. Open the project in your account and go to the [Items catalog > All items > Virtual items](https://xsolla.com/for/free-to-play-pc/account/0/projects/0/storefront/virtual-items) section.

   **End of audience: Free-to-play PC games**

   **Audience: Premium PC games**

1. Open the project in your account and go to the [Items catalog > All items > Virtual items](https://xsolla.com/for/premium-pc-games/account/0/projects/0/storefront/virtual-items) section.

   **End of audience: Premium PC games**

   **Audience: Web games**

1. Open the project in your account and go to the [Items catalog > All items > Virtual items](https://xsolla.com/for/web-games/account/0/projects/0/storefront/virtual-items) section.

   **End of audience: Web games**

   **Audience: Mobile games**

1. Open your project in the account for mobile games and go to the [Catalog](https://xsolla.com/for/mobile-games/account/0/projects/0/storefront/virtual-items) section.

   **End of audience: Mobile games**

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

   ![virtual items 1](https://cdn.xsolla.net/developers/current/images/items-catalog/items-type/virtual-items-1.svg)

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)

   ![create item general settings](https://cdn.xsolla.net/developers/current/images/items-catalog/items-type/create-item-general-settings.png)

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](/api/catalog/virtual-items-currency-catalog/get-virtual-items#virtual-items-currency-catalog/get-virtual-items/t=response&c=200&path=items/image_url).

   ![create item media](https://cdn.xsolla.net/developers/current/images/items-catalog/items-type/create-item-media.png)

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](/items-catalog/catalog-features/pricing-policy).
    * To create a free item, select **Free item**.

   > [!NOTE]
   > An item can have prices in several real and virtual currencies. In this case, you must specify a default currency for each type — one among the real currencies and one among the virtual currencies.
   >
   > You can specify a price in virtual currency only if the virtual currency has already been created in the project.

   ![create item paid](https://cdn.xsolla.net/developers/current/images/items-catalog/items-type/create-item-paid.png)

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.

   > [!NOTE]
   > By default, an item is hidden from the catalog once the purchase limit is reached. If automatic limit reset is configured, the **Show item even after users reach the purchase limit** checkbox lets you keep the item visible until the next reset cycle begins.

   ![create item limits](https://cdn.xsolla.net/developers/current/images/items-catalog/items-type/create-item-limits.png)

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.

   > [!NOTE]
   > To add another display period for the item in the catalog, click **+**. If an item has multiple display periods, each must have an end date. The display period ends at the last second of the specified minute. For example, if an end time is set to 12:00, the display period runs until 12:00:59.

   ![create item display](https://cdn.xsolla.net/developers/current/images/items-catalog/items-type/create-item-display.png)

8. Configure attributes using one of the following options (optional):
    1. [Add attributes and their values in JSON format](/items-catalog/catalog-features/item-attributes/#item_attributes_adding_json_v1).
    2. [Manually create attributes and their values, and link them to items](/items-catalog/catalog-features/item-attributes/#item_attributes_creation_pa).

   ![create item attributes](https://cdn.xsolla.net/developers/current/images/items-catalog/items-type/create-item-attributes.png)

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.

   > [!NOTE]
   > This parameter may be required for games distributed in countries with legal restrictions on such mechanics.

10. Click **Create**.

11. In the window that opens, select the [item status](/items-catalog/catalog-features/items-availability/#items_catalog_features_items_availability) and click **Continue**.

   ![create item status](https://cdn.xsolla.net/developers/current/images/items-catalog/items-type/create-item-status.png)

The created item will appear in the **All items** section.

### Set up via API {#general_how_to_set_up_via_api}

To set up virtual items, you can use the calls from the **Admin** subsection in the [Virtual items and currency](/api/catalog/virtual-items-currency-admin/admin-get-virtual-items-list/) group.

> [!NOTE]
> Calls from the **Admin** subsection aren’t intended for building a store catalog on the front end. You shouldn’t use them for landing pages, web stores, and in-game logics.

| Task           | API call                                                                                                                                              |
|:-------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Create a virtual item.            | [Create virtual item](/api/catalog/virtual-items-currency-admin/admin-create-virtual-item/).                                                                      |
| Get virtual item information.               | [Get virtual item](/api/catalog/virtual-items-currency-admin/admin-get-virtual-item/).                                                                             |
| Get a list of virtual items.          | [Get list of virtual items](/api/catalog/virtual-items-currency-admin/admin-get-virtual-items-list).                                                                        |
| Get a list of virtual items by specified group. | In the [Get list of virtual items by specified group external id](/api/catalog/virtual-items-currency-admin/admin-get-virtual-items-list-by-group-external-id/) API call pass the parameter `external_id`.                                    |
| Get a list of virtual items by group for administration.    | In the [Get list of virtual items by specified group id](/api/catalog/virtual-items-currency-admin/admin-get-virtual-items-list-by-group-id/) API call pass the parameter `group_id`.                                                |
| Update a virtual item.            | [Update virtual item](/api/catalog/virtual-items-currency-admin/admin-update-virtual-item/).                                                                       |
| Delete a virtual item.            | [Delete virtual item](/api/catalog/virtual-items-currency-admin/admin-delete-virtual-item/).                                                                       |
| Limit the number of virtual items available for purchase.             | In the [Create virtual item](/api/catalog/virtual-items-currency-admin/admin-create-virtual-item/) or [Update virtual item](/api/catalog/virtual-items-currency-admin/admin-update-virtual-item/) API calls, pass the following parameters:
- `limits` — specifies the maximum quantity of virtual items available for purchase.
- `limits.recurrent_schedule` — defines how often the limit resets. |

   > [!NOTE]
   > For more information about limits, see the following guides:
   > * [Number limited offers](/items-catalog/catalog-features/items-catalog-number-limits/)
   > * [Time limit for displaying items in store](/items-catalog/catalog-features/limiting-display-time/#shop_builder_how_to_limit_display_time)
   > * [Regional sales restrictions](/items-catalog/catalog-features/regional-restrictions/)
   > * [Local prices](/items-catalog/catalog-features/pricing-policy/)
   > * [Managing item availability in catalog](/items-catalog/catalog-features/items-availability/#items_catalog_features_items_availability)

## Display virtual items in store {#how_to_display_virtual_items}

The display of virtual items depends on how the catalog is implemented — [through the site editor](#general_how_to_display_via_site_builder) or [via API](#how_to_display_virtual_items_via_api).

### Display via site editor {#general_how_to_display_via_site_builder}

To display a virtual item on your website:

1. [Create a virtual item](#general_how_to_set_up_via_pa).

   > [!NOTE]
   > To display virtual items in site editor, [create groups](/items-catalog/catalog-features/group-items/) in advance – virtual items are displayed in the store catalog only as part of a group.

   **Audience: all other audiences**

2. In your project in Publisher Account, go to the [Storefronts > Websites](https://publisher.xsolla.com/0/projects/0/site-builder) section.

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

   ![virtual items sb 1](https://cdn.xsolla.net/developers/current/images/items-catalog/items-type/virtual-items-sb-1.svg)

   **End of audience: all other audiences**

   **Audience: Free-to-play PC games**

2. In the project in your account, go to the [Storefronts > Websites](https://xsolla.com/for/free-to-play-pc/account/0/projects/0/site-builder) section.

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

   **End of audience: Free-to-play PC games**

   **Audience: Premium PC games**

2. In the project in your account, go to the [Storefronts > Websites](https://xsolla.com/for/premium-pc-games/account/0/projects/0/site-builder) section.

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

   **End of audience: Premium PC games**

   **Audience: Web games**

2. In the project in your account, go to the [Storefronts > Websites](https://xsolla.com/for/web-games/account/0/projects/0/site-builder) section.

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

   **End of audience: Web games**

   **Audience: Mobile games**

2. In your project in the account for mobile games, go to the [Web Shop](https://xsolla.com/for/mobile-games/account/0/projects/0/site-builder) section.

3. Click the pane of the desired site.

   ![open site in builder](https://cdn.xsolla.net/developers/current/images/guides/site-builder/open-site-in-builder.svg)

   **End of audience: Mobile games**

4. If your site includes multiple pages, select the one you need: 
   a. Click the current page title at the top of the editor.
   b. 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.

   ![virtual items sb 2](https://cdn.xsolla.net/developers/current/images/items-catalog/items-type/virtual-items-sb-2.svg)

6. [Set an item card layout](/solutions/web-shop/create-web-shop/create-site/#web_shop_guide_create_site_with_auth_store).

7. After making all necessary changes and preparing your website for launch:
   a. In the upper-right corner of the site editor, click **Publish**.
   b. Check the boxes next to the pages you want to publish.
   c. Click **Publish**.

   > [!NOTE]
   > If website publication is not available, make sure all the conditions are met:
   > * There are no empty sections on the website (marked with a red indicator).
   > * [The licensing agreement with Xsolla has been signed](/get-started/work-in-pa/legal-aspects/).
   > * The main page is published or selected for publication. You cannot publish child pages before the main page.

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](#general_how_to_set_up_via_pa).

### Get virtual item information via API {#how_to_display_virtual_items_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](/api/catalog/virtual-items-currency-admin/admin-get-virtual-items-list/) method group. Authorization is not required to use these methods.

| Task      | API call                                                                              |
|:--------------------------------|:------------------------------------------------------------------------------------------------------------|
| Get a virtual item by SKU.      | In the [Get virtual item by SKU](/api/catalog/virtual-items-currency-catalog/get-virtual-items-sku/) API call pass the parameter `item_sku`.        |
| Get a list of virtual items.     | [Get virtual items list](/api/catalog/virtual-items-currency-catalog/get-virtual-items/).           |
| Get a list of virtual items by specified group. | In the [Get items list by specified group](/api/catalog/virtual-items-currency-catalog/get-virtual-items-group/) API call pass the parameter `external_id`. |
| Get a full list of virtual items in the project.      | [Get all virtual items list](/api/catalog/virtual-items-currency-catalog/get-all-virtual-items/).        |

## Grant virtual items to users {#how_to_grant_virtual_items}

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](/items-catalog/catalog-management/import-catalog-external/), 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](/webhooks/combined-webhooks/successful-order-payment/) webhook.

Refer to the [Set up order status tracking](/virtual-goods/own-ui/server-side-token-generation/set-up-order-tracking/#payments_integration_order_tracking) section for more details on this and other methods of retrieving purchase data.