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:
   • via Publisher Account
   • via API calls
2. Set up Store.
3. Get a user’s order status.

Create via Publisher Account

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:
   • For virtual items — Create virtual item
   • For currency package — Create virtual currency package
   • For bundles — Create bundle
   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

{
  "method": "POST",
  "url": "https://mybestgame.com/xsolla/notification",
  "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
  }
}

• 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:

• If the user’s cart contains both paid and free items, call the standard Create order with all items from particular cart and Create order with all items from current cart API for creating orders. Users will make a payment for the order through the Pay Station payment form.
• If the user’s cart contains only free items, call the Create order with free cart and Create order with particular free cart API to get a free cart. In this case, the payment interface will not be used.

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