Bundles

How it works

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

Main features:

  • Add items of different types to a bundle:
    • virtual currency (including the platform-dependent currency)
    • package of virtual currency
    • game keys for preselected DRMs
    • virtual items including nonrenewing subscriptions
    • bundles
  • Configure the bundle pricing in real and virtual currencies.

A bundle automatically unpacks after:

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 cancelling 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.

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, and who have integrated one of the following products (or both):

  • In-Game Store with configured Virtual Items or Virtual Currency modules.
  • Buy Button with the configured Game Keys module.

How to get it

Prerequisites

  1. Create your Xsolla Publisher Account.
  2. Go to your project.

  1. Go to Project settings > Integration settings and make sure that the Integrate Commerce API toggle is set to On.

  1. Configure modules for In-Game Store or Buy Button.

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 DRM to a bundle, pass an array with SKUs of needed DRMs to Create bundle or Update bundle methods.

Copy
Full screen
Small screen
"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 Account Manager to do it.
Copy
Full screen
Small screen
"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 Account Manager to do it.
Copy
Full screen
Small screen
"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.