Bundles

How it works

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

Main features:

• Adding items of different types to a bundle:
  • virtual currency
  • package of virtual currency
  • game keys for preselected platforms
  • virtual items
  • bundles
• Free bundle.
• Configuring the bundle pricing in real and virtual currencies. You can set up prices in several real or virtual currencies. Make sure you select a default currency in this case.
• Setting regional prices for bundles.
• Limiting the number of bundles available for purchase.
• Setting a time limit for displaying bundles in the store.
• Restricting bundle availability by region.

• You can’t add the same bundle to the bundle.
• You can’t create an empty bundle.
• If a bundle includes keys and the available keys are exhausted, the sale of that bundle is paused.
• Setting regional restrictions for bundles is only available via API calls.

How to set up

Set up via Publisher Account

To create a bundle:

1. In your project in Publisher Account, go to the Items catalog > All items section.
2. Click Add and select Bundle from the drop-down list.

3. Specify the following parameters:
   • Image (optional).
   • SKU.
   • One or several groups the bundle should belong to.
   • Name.
   • Description (optional).
4. Configure bundle attributes (optional) using one of the following methods:
   • Add attributes and their values in JSON format.
   • Manually create attributes and values, and link them to specific items.
5. Click Next.
6. If partner-side personalization is enabled, you can choose between a standard and a dynamic bundle type. Dynamic bundles allow you to skip item creation in Xsolla and instead return bundle contents generated by your server when the catalog is requested. If partner-side personalization is disabled, the bundle type selector is not displayed, and a standard bundle is created automatically.

7. Add items to the bundle:
   1. Select the item type.
   2. Specify one or more item SKUs to be included in the bundle.
   3. Set the quantity for each SKU.

8. Click Next.
9. Set the bundle price in the Paid or Free field:
   • To create a free bundle, select Free bundle.
   • To set a price, select Paid bundle and specify the price in real or virtual currency. You can’t create a bundle with a price of zero. If needed, configure regional prices.
10. To limit the number of bundles available for purchase, turn on the Limit bundle purchases per user toggle and enter the desired quantity.

11. To configure how often the limit resets:
    1. From the drop-down list, select a period:
       • Daily.
       • Weekly.
       • Monthly.
       • Custom interval — this is calculated starting from the bundle’s display start date.
       • No regular refresh.
    2. Set up the reset schedule based on the selected period.

12. Click Next.

13. Configure how the bundle is displayed in the store:
    1. Choose the status.
    2. Set a display time limit for the bundle (optional): specify the time zone and the beginning and the end of the period. If you don’t want to indicate the end of the item display period, check the No end date box.

14. Click Next.
15. Check the settings and click Save.

Set up via API

To set up bundles, you can use the calls from the Admin subsection in the Bundles group.

1"content": [
2  {
3     "sku": "brilliant_game_sku_steam",
4     "quantity": 1
5  }
6]

To limit the number of bundles available for purchase, use the Create bundle or Update bundle API calls with the following parameters:

• limits — specifies the maximum number of bundles available for purchase.
• limits.recurrent_schedule — defines how often the limit resets.

You can also configure the bundle’s display time limit in the store and set regional restrictions.

Display bundles in store

Bundles are displayed in the catalog depending on how it is implemented — through the site builder or via API.

Display via site builder

To display bundles on your website:

1. Create bundles.
2. In your project in Publisher Account, go to the Storefronts > Websites section.
3. In the pane of the desired site, click Open Site Builder.

4. In the Store block, go to the Store section.
5. In the Item type field, select Bundles.

6. In the Item group field, select their group.
7. Choose an item card layout.

8. If needed, customize the card layout by turning on the corresponding toggles in the card layout settings.

9. After making all necessary changes and preparing your website for launch:
   1. In the upper-right corner of the site builder, click Publish.
   2. Check the boxes next to the pages you want to publish.
   3. Click Publish.

Once the site is published, a section with bundles will become available. If no bundles are displayed, check that their status is set to Available and that no time-based display limit is active.

Get bundle information via API

If your catalog is configured using API, bundle data is returned through the calls available in the Catalog subsection:

• Get list of bundles
• Get list of bundles by specified group
• Get specified bundle

Set up webhooks

You can configure which item data is included in the Successful payment for order and Order cancellation webhooks via the items array.

Grant bundles to users

Depending on the item type and integration settings, the bundle is granted to the user in one of the following ways:

• If you’ve integrated PlayFab, virtual currency and items are granted to the user’s PlayFab inventory automatically.
• If you use a custom delivery system, all virtual items and currency are granted on your side. We recommend setting up a webhook handler to receive order data on your backend. The necessary data is included in the Successful payment for order webhook.
• If bundle content delivery is not disabled, after a bundle purchase, all items included in the bundle are listed in the items array of the Successful payment for order webhook as separate items. If a bundle contains another bundle, it will also be unpacked and passed as separate items.

Refer to the Set up order status tracking section for more details on this and other methods of retrieving purchase data.