Free items

How it works

Free items are a type of item that the user can get without spending virtual or real currency. These include:

  • Virtual items
  • Bundles
  • Virtual currency packages

Free items are only available to authorized users. Unauthorized users can only view the catalog of free items.

Examples of usage:

  • You can give away free items on important dates for your project (for example, on the day the project was founded) to reward users for their loyalty.
  • You can give away free starter packs for the game in the store to attract new users to the game.

You can limit the free giveaway of unique items if the user already has them.

Who can use it

  • For partners who already have the In-Game Store and want to set up a new type of product — free items.
  • For partners who want to increase the loyalty of current users or attract new players.

Integration flow

  1. Create free items in the following ways:
  2. Set up Store.
  3. Get a user’s order status.

Create via Publisher Account

To create a free item (based on the example of virtual items):
  1. Open your project in Publisher Account.
  2. Click Store in the side menu.
  3. In the Virtual Items pane, click Configure.
  4. Click + and select Create item from the drop-down list.
  5. Specify:
    • Image
    • SKU
    • One or several groups the item should belong to
    • Name
    • Description
    • Item property: consumable, nonconsumable, or time-limited item
  6. In the Price settings block, choose Free item.
  7. If you want to limit the availability of items to specific users, switch the Limit number of times one user can buy this item toggle to On and specify the number.
  8. If you want to show an item in the store, set the Show item in store toggle to On.
  9. Click Create item.

Create via API calls

  1. To create free items, use API calls from the Admin subsection:When creating or editing an item, pass is_free = true in the request body.
  2. If you want to limit the availability of items to specific users, call any API method for creating or editing an item and specify the value of the limits.per_user parameter.

Set up Store

Fast purchase

If a user uses fast purchase (a user doesn’t use a cart), you need to call the Create order with specified free item API to provide the opportunity to receive free items. The delivery of items to the user’s inventory occurs immediately after a successful request to this method (without the need to open the Pay Station payment form). Xsolla sends a Successful payment of the order webhook that the item was delivered.
Sending the Successful payment of the order webhook occurs immediately after the free items are delivered. In this case, the Payment webhook is not sent.
Example of the request:
Full screen
Small screen

  "method": "POST",
  "url": "",
  "body": {
    "items": [
        "sku": "gift_direct_game_reward-supercoin",
        "type": "virtual_currency",
        "is_pre_order": false,
        "quantity": 500,
        "amount": "0",
        "promotions": [

        "sku": "package-500_supercoin",
        "type": "bundle",
        "is_pre_order": false,
        "quantity": 1,
        "amount": "0",
        "promotions": [

        "sku": "xsolla-giveaway_offer_11_14_22",
        "type": "bundle",
        "is_pre_order": false,
        "quantity": 1,
        "amount": "0",
        "promotions": [

    "notification_type": "order_paid",
    "order": {
      "id": 12345678,
      "mode": "default",
      "currency_type": "unknown",
      "currency": null,
      "amount": "0",
      "status": "paid",
      "platform": "xsolla",
      "comment": null,
      "invoice_id": null,
      "promotions": [

    "user": {
      "external_id": "1234567812345678",
      "email": null
  "headers": {
    "Authorization": "Signature 3b840ccefea111dcdfd111db1fdc6df969a3ec11",
    "Accept": "application/json",
    "Content-Type": "application/json"
  "type": "webhook_payment",
  "callback_parameters": {
    "order_id": 12345678
For free items, the order.invoice_id parameter is set to null.
In response, a webhook should be sent from your side:
  • If your listener correctly accepted and processed the webhook — HTTP response code 200 or 204.
  • If the expected error occurs — HTTP response code 4xx.
  • Note
    In this case, the items are added to the player’s inventory and the order is marked as successful on Xsolla’s side.
  • Your listener may also return a 5xx HTTP response code for temporary errors on your server. In this case, the Xsolla alert service uses a retry mechanism.

Cart purchase

If a user uses cart purchase:

The webhook example is similar to the example for fast purchase.

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: January 22, 2024

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!