Bundles

How it works

Bundle is a set of several items that are sold as a single unit.

Main features:

A bundle automatically unpacks after successful purchase. If a bundle includes another bundle, the included bundle automatically separates into standalone items.

Items delivery method from an unpacked bundle depends on the item type:

Note
If you implemented the In-Game Store logics to your servers, you can set up item purchase webhooks. The webhook will contain a bundle and all its contents.

When the buyer returns the bundle by canceling a transaction (for example), all granted items from the bundle are automatically withdrawn from the user. If they spent some of the items, the remaining items are still withdrawn.

Restrictions:

  • You can’t add the following items to the bundle:
    • the same bundle
    • physical goods
  • You can’t create an empty bundle.
  • The bundle sales are paused after you run out of keys to sell and these keys are included in the bundle.
  • The bundle price should be a fixed value of real and/or virtual currency.
  • You can configure regional restrictions for a bundle only via API.

Limiting number of bundles available for purchase

You can limit the purchase of bundles. For example, you can limit:

  • the number of bundles per user
  • welcome bundles that are only available for purchase once

If the user has reached the specified limit, the bundle will not be displayed in the catalog. If the bundle contains a virtual currency package or item with a purchase limit and the user has already purchased the allowed amount, the bundle will not be displayed in the catalog.

You can display the maximum available number of bundles and the remaining number of bundles that is available to the user.

To set a purchase limit when creating a bundles in Publisher Account, switch the Limit number of times one user can buy this bundle toggle to On and specify the number of times the bundle can be bought.

You can use the methods of the Catalog subsection from the Bundles method group to get information about bundles.

In the response, you will receive the following information in addition to information about the bundle:

  • the maximum number of bundles a user can buy
  • the remaining number of bundles available for the user to purchase

You can read more about how to set up or update restrictions in the Limits for user instructions.

Note

For unauthorized users, the maximum number of bundles they can buy is always displayed. To display the remaining number of bundles to the user (subject to the current limit), pass user authorization data when you request the bundles catalog using the methods of the Catalog subsection from the Bundles method group.

To correctly display the number of bundles that are available to the user, you need to configure authentication.

Response example:
Copy
Full screen
Small screen
  • json

{
  "items": [
    {
      "sku": "kg_1",
      "name": "kg_10.00_bundle",
      "type": "bundle",
      "description": "pricePoint_44056_1",
      "image_url": null,
      "long_description": null,
      "attributes": {
        "external_id": "genre",
        "name": "Genre",
        "values": [
          {
            "external_id": "genre_e3364991f92e751689a68b96598a5a5a84010b85",
            "value": "Casual"
          },
          {
            "external_id": "genre_eba07bfd0f982940773cba3744d97264dd58acd7",
            "value": "Strategy"
          },
          {
            "external_id": "genre_b8d0c6d8f0524c2b2d79ebb93aa3cd0e8b5199a8",
            "value": "Mobile"
          }
        ]
      },
      "is_free": false,
      "order": 999,
      "groups": [],
      "price": {
        "amount": 9.99,
        "currency": "USD",
        "amount_without_discount": 9.99
      },
      "total_content_price": {
        "amount": 10.99,
        "currency": "USD",
        "amount_without_discount": 10.99
      },
      "media_list": [],
      "virtual_prices": [],
      "can_be_bought": true,
      "bundle_type": "standard",
      "limits": {
        "$ref": "./Catalog_item_limits.yaml"
      },
      "content": [
        {
          "sku": "big_rocket",
          "name": "Big Rocket",
          "description": "Big Rocket - short description.",
          "image_url": "https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png",
          "type": "virtual_currency",
          "quantity": 100,
          "virtual_item_type": "non_consumable",
          "attributes": {
            "external_id": "size",
            "name": "Size",
            "values": [
              {
                "external_id": "size_e3364991f92e751689a68b96598a5a5a84010b85",
                "value": "Large"
              }
            ]
          },
          "is_free": false,
          "groups": [],
          "price": {
            "amount": 10.99,
            "currency": "USD",
            "amount_without_discount": 10.99
          },
          "virtual_prices": [],
          "limits": {
            "per_user": {
              "total": 5,
              "available": 5
              },
            "per_item": null
           },
          }
        }
      ]
    }
  ]
}
Note

Xsolla ensures the limits are not exceeded and prevents users from purchasing more bundles than the set limit.

When opening the payment interface and paying for a bundle, all unpaid orders with this bundle become invalid.

Example: the user can open the payment form for a bundle with a purchase restriction in several browser tabs until the bundle has been purchased. This automatically results in the creation of multiple orders for the same bundle. After purchasing a bundle in one tab, Xsolla will void all unpaid orders with the same bundle.

Limiting the display time for bundles in the store

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 a bundle in advance without displaying it in the catalog
  • motivate users to buy bundles by displaying a timer next to the item
Note
When you create a catalog interface using Site Builder, the timer is displayed automatically. When you create a catalog in your own interface, you need to implement the timer.

To set a time limit for displaying a bundle in the store via Publisher Account, select Time period and specify the time zone, the beginning, and end of the period. To not indicate the end of the bundle display period, check the No end date box.

To set a time limit for displaying a bundle in the store via API, pass the following parameters in the Create bundle or Update bundle 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, pass null

You can set up multiple periods for displaying a bundle in the store. To do this, in the Create bundle or Update bundle method, pass an array of objects with the start and end dates of all periods.

Example:

Copy
Full screen
Small screen
    "periods": [
      {
        "date_from": "2022-06-10T14:00:00+03:00",
        "date_until": "2022-06-30T14:00:00+03:00"
      },
       {
        "date_from": "2022-07-10T14:00:00+03:00",
        "date_until": "2022-07-30T14:00:00+03:00"
      },
       {
        "date_from": "2022-08-10T14:00:00+03:00",
        "date_until": "2022-08-30T14:00:00+03:00"
      }
]

    Who can use it

    For partners who want to sell sets of items for a price lower than the initial total of all items in the bundle, which increases sales and helps to get new players.

    How to get it

    Integration flow

    1. Set up a bundle.
    2. Implement getting of bundles in a catalog.

    Set up bundle

    Set up bundles in one of the following ways:

    Set up via Publisher Account

    1. Go to Publisher Account > Store > Bundles and click Create bundle.
    2. Specify the following parameters for a bundle:
      1. Image
      2. Name
      3. Description
      4. Contents
      5. Price
      6. Display in Store
    3. Check the settings and click Save.

    Set up via API methods

    To set up bundles, you can use the methods from the Admin subsection from the Bundles method group.
    Notice
    Methods from the Admin subsection aren’t created for building a catalog in the store on the frontend side. You should use them for landing pages, web stores, and in-game logics.

    Add game key to bundle

    To add a game key for a selected platform to a bundle, pass an array with SKUs of needed platforms to Create bundle or Update bundle methods.

    Copy
    Full screen
    Small screen
    • http
    
"content": [{
     “sku”: “brilliant_game_sku_steam”,
     “quantity”: 1
  }
]

    Set up regional restrictions

    To set up regional restrictions for a bundle, pass an array with IDs of supported regions to Create bundle or Update bundle methods.

    Note
    Make sure you set up regions in a project via API methods or contact your Customer Success Manager to do it.
    Copy
    Full screen
    Small screen
    • http
    "regions": [{
     “id”: “123”
  }, {
     “id”: “456”
  }
]

    Set up regional prices

    To set up regional prices for a bundle, pass an array of objects with price settings for regions to Create bundle or Update bundle methods.

    Note
    Make sure you set up regions in a project via API methods or contact your Customer Success Manager to do it.
    Copy
    Full screen
    Small screen
    • http
    "regional_prices": [{
     “region_id”: “123”,
     “country_iso”: “CHN”,
     “amount”: 40,
     “currency_iso”: “CNY”,
     “is_default”: true,
     “is_enabled”: true
  }
]

    Get bundles in a catalog

    To get a catalog of bundles, you can use the methods from the Catalog subsection from the Bundles method group.
    Note
    Methods form the Catalog subsection are created for building a catalog in the store on the frontend side. They don’t require authorization.
    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.
    Last updated: November 8, 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!