Time limit for displaying items in store

How it works

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. When you create a catalog interface using site builder, the timer is displayed automatically. When you build the catalog using a custom interface, the timer must be implemented on your side.

Time limit configuration is available for the following scenarios:

• sale of in-game items — virtual items, virtual currency packages, and bundles
• sale of games and DLC via game keys

Configure and update limits

To create an item with a limited number of uses:

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 and update via API calls

To set a time limit for displaying items in the store, use the following API calls:

• Create virtual item or Update virtual item
• Create virtual currency or Update virtual currency
• Create virtual currency package or Update virtual currency package
• Create bundle or Update bundle
• Create game, Update game by SKU or Update game by ID

Pass following parameters to the item creation or item update 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, specify only one period and pass “periods[0].date_until”: null.

You can set up multiple periods for displaying an item in the store. To do this, pass an array of objects with the start and end dates of all periods in the API calls.

Example:

 1"periods": [
 2      {
 3        "date_from": "2022-06-10T14:00:00+03:00",
 4        "date_until": "2022-06-30T14:00:00+03:00"
 5      },
 6       {
 7        "date_from": "2022-07-10T14:00:00+03:00",
 8        "date_until": "2022-07-30T14:00:00+03:00"
 9      },
10       {
11        "date_from": "2022-08-10T14:00:00+03:00",
12        "date_until": "2022-08-30T14:00:00+03:00"
13      }
14]

The catalog retrieval API calls return the items that are displayed in the store at the time of the request. To obtain information about items whose display period has not yet started or has already expired, pass the show_inactive_time_limited_items parameter with a value of 1 when requesting the catalog.

Display limits in the catalog of items

The display of time-limited items in the catalog depends on how it is implemented — either through the site builder or via API.

Display via site builder

If you use a site builder, time limits are displayed automatically. 30 days before the end of an item’s sale period, a timer automatically appears on the item card and shows the remaining time:

• If more than a week remains until the end of the sale, the timer shows days and hours.
• If more than one day remains until the end of the sale, the timer shows hours and minutes.
• If less than one day remains until the end of the sale, the timer shows minutes and seconds.

Get limit information via API

If the catalog is implemented using API, item’s sale period information is returned in the items.periods array in the following catalog-related API calls:

• Get virtual items list
• Get virtual currency list
• Get virtual currency packages list
• Get bundles list
• Get games list

The data about the dates when an item is available for sale can be used to display limits in the catalog — for example, to show the period during which a user can purchase the item.