Item purchase limits
How it works
You can set a purchase limit per user and configure scheduled resets for these limits.
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
You can enable periodic limit resets to:
- allow repeat purchases
- synchronize data with your system when items are sold across multiple game publishing platforms
- the item catalog using calls from the Catalog subsection of Virtual Items & Currency group
- the game catalog using calls from the Catalog subsection of Game Keys group
Note
Xsolla enforces limits and prevents users from purchasing more items than the set limit:
- When the payment UI is opened and an item is paid for, all unpaid orders containing that item become invalid.
- Example: A user can open the payment form for a limited item in multiple browser tabs or different browsers before completing the purchase, which creates multiple orders for the same item. Once the purchase is completed in one tab, Xsolla cancels all unpaid orders for that item.
- When a payment is refunded or order is cancelled, limits are not reset. You can reset them using the following API calls: Refresh all purchase limits for specified user and Refresh all promotion limits for specified user.
- Example: A user can purchase an item that has purchase limits, use it in the game, and then request a refund. If limits were reset automatically, the user could buy the item again, use it, and repeat this cycle, effectively bypassing the intended limits. To prevent this, the limits are not reset when a payment is refunded or an order is canceled.
Configure and update limits
Configure and update in Publisher Account
Note
- The configuration process below is shown using virtual items as an example.
- Before configuring virtual items, it is recommended to create groups. Groups allow you to build a multi-level catalog and manage how items are displayed in your store.
- In Publisher Account, you can update limits for a specific item for all users. Advanced configuration options are available via API calls.
- Open your project in Publisher Account and go to the Items catalog > All items > Virtual items section.
- Click Add and select Virtual items.
- Specify the following parameters:
- image
- SKU
- one or several groups the item should belong to
- name
- description
- prices
Note
You can’t create an item without specifying the price in real or virtual currency. You can’t create an item with a zero price value. If necessary, configure regional prices.
- To limit the number of times a user can buy an item, set the Limit the number of times one user can buy this item toggle to On and specify the limit.
- To set how often limits are refreshed:
- In the drop-down list, select the period:
- Daily
- Weekly
- Monthly
- Custom interval. The interval is calculated starting from the start date of the item’s display period in the store.
- No regular refresh
- In the drop-down list, select the period:
- Set the update schedule by specifying the parameters corresponding to the period.
- To set a display period for the item in the catalog, select Limited time, specify the time zone, start date, and end date. To make the item available indefinitely, select No end date.
- Click Create item.
To configure or update limits for an existing item:
- Open your project in Publisher Account and go to the Items catalog > All items > Virtual items section.
- Open the group containing the item.
- In the row of the item, click ••• and choose Edit in the drop-down list.
- In the Limits for single user section, set the limit and/or select the limit reset frequency, then specify the time and time zone.
- Click Save changes.
Note
You can set limits on the number of game keys available per user in the Items catalog > All items > Game keys section.
To configure the limit reset frequency for game keys, use the corresponding API calls.
Set up and update via API calls
To set daily, weekly, or monthly limits, pass the recurrent_schedule array in the following API calls:
| Feature | API call |
|---|---|
| Refresh limits for specified item for all or specified users. | Refresh purchase limit. |
| Clear all item limits for specified user. | Refresh all purchase limits for specified user. |
| Change the limit on the purchase of a specified item for a specified user. | Set number of items available to specified user. |
| Get information about what limits are configured for a specified item for a specified user. | Get number of items available to specified user. |
| Increase the number of items that can be purchased for a specified user. | Increase number of items available to specified user. |
| Decrease the number of items that can be purchased for a specified user. | Decrease number of items available to specified user. |
Display limits in the catalog of items
Limits on item sales are displayed in the catalog depending on how it is implemented — either through the site builder or via API.
Display via site builder
If you use the site builder, limits are displayed automatically — an item card shows a counter of items available to the user.
Note
To attract attention to promotional items, we recommend using the Featured offer card style.
Get limit information via API
If the catalog is implemented using API, limit information is returned in the items.limits 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
can_be_bought = false.
You can update these limits as needed.
This data can be used to display limits in the catalog — for example, to show the maximum number of items available for purchase.Was this article helpful?
Thank you for your feedback!
We’ll review your message and use it to help us improve your experience.Found a typo or other text error? Select the text and press Ctrl+Enter.
