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 platforms
  • virtual items including time-limited items
  • bundles
• Configure 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.
• Free bundle.
• Limiting the number of bundles available for purchase.
• Limiting the display time for bundles in the store.

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

After a bundle is unpacked, each item is delivered to the user in one of the following ways — depending on its type and the integration settings:

• Via PlayFab – for virtual currencies, virtual items, time-limited items, and bundles, if PlayFab integration is enabled.
• By email – for game keys.
• Through your own delivery system using data from the Successful payment for order webhook. This method applies to all types of items if:
  • PlayFab integration is not used.
  • You prefer to manage item delivery to users on your own server.

When a bundle is refunded, for example, due to a transaction cancellation, an Order сancellation webhook will be sent. This webhook will include all items from the bundle in an unpacked format — as a list of individual items contained in the bundle. Use the webhook data to deduct the purchased items from the user’s account.

Restrictions:

• You can’t add the same bundle to the bundle.
• 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.

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.

{
  "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
           },
          }
        }
      ]
    }
  ]
}

Limiting the display time for bundles in the store

• 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

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:

"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

• via Publisher Account
• via API methods

Set up via Publisher Account

1. Open your project in Publisher Account and go to Store > Bundles section.
2. Click + and select Create bundle from the drop-down list.
3. Add:
   • Image (optional).
   • SKU.
   • One or several groups the bundle should belong to.
   • Name.
   • Description (optional).
   • Contents.
4. Set the bundle price:
1. Define the prices or create a free bundle:
1. To create a free bundle, in the Paid or Free field, select Free bundle.
2. To set a price, in the Paid or Free field, select Paid bundle and specify the price in real or virtual currencies. If needed, configure regional prices.
2. Set a purchase limit for the bundle (optional). To do this, turn on the Limit number of times one user can buy bundle toggle to On and specify the number of bundles a user can purchase.
5. Click Next.
6. Configure the display of the bundle in the store:
   • Change the status to Available.
   • Set a time limit for displaying a bundles in the store (optional). To do this, select Time period and specify the time zone, 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.
7. Click Next.
8. Check the settings and click Save.

Set up via API methods

Add game key to bundle

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

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

"regions": [{
     “id”: “123”
  }, {
     “id”: “456”
  }
]

Set up regional prices

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

"prices": [
      {
        "amount": 100,
        "currency": "USD",
        "is_enabled": true,
        "is_default": true
      },
      {
        "amount": 200,
        "currency": "CZK",
        "country_iso": "CZ",
        "is_enabled": false,
        "is_default": false
      }
    ]

Get bundles in a catalog