Bundle

The available options to target bundles of items from a set of groups

When you specify the groups key within an action, all the elements of all the selected groups are targeted. You can add the bundle object to pick specific items from those groups (based on predefined sorting functions and different bundling strategies), thus enabling you to create different types of powerful bundle promotions.

Bundles consider the groups defined by the action as their universe, that's why it's mandatory to define one or more groups if you want the action to be applied to bundles and the bundle sorting and selection to work properly.

How bundles work

The bundling process consists of two main steps:

1. Sorting — the items of the group(s) targeted by the action are first sorted according to a specified function applied to a numeric field of the action's selector.

2. Selection — the sorted items are then selected based on the desired bundling strategy.

As a consequence of that, to configure a bundle you must define at least its type and how to sort the targeted items. Based on the type of bundle some restrictions may apply, for example:

• The list of required parameters may vary.

• Some optional key (e.g. value) may be available or not.

Key	Type	Description	Example
type	String	The bundle type. Can be one of balanced or every. Default is balanced.	"every"
sort	Object	Additional information on how to sort the targeted items.	Learn more here.
value	Integer	The number of items to be considered during the bundle calculation. Required for bundles of type every, cannot be set for bundles of type balanced.	2

Sort

Use the bundle.sort object to specify the sorting function to apply before calculating the bundle and the field on which to execute it:

Key	Type	Required	Description	Example
attribute	String		The field of the resource specified in the action's selector on which to apply the bundle sorting. Works with numeric fields only.	"quantity"
direction	String		The type of sorting to apply on the targeted items before building the bundle. Can be one of asc or desc.	"asc"

You can use bundles on percentage, fixed amount, and fixed price actions only.

Bundle types

At the moment two types of bundles are available, based on how many groups (one or more) you specify in the actions.groups array:

Type	Groups	Description	Learn more
balanced	> 2	Ensures an even distribution of items across groups based on the sorting.	Balanced
every	1	Maximizes the number of items picked from the group's ordered list as long as it is equal to or a multiple of the specified value.	Every

When to use one or the other bundling strategy it depends on your needs:

• Balanced — can cover a wide range of the most common use cases, mostly dealing with strictly structured bundles where each item type needs to appear in equal quantities.

• Every — is more specific and works best for bulk discounts and progressive promotions depending on quantity multiples.

In both cases, if one (or more) of the groups specified in the related actions.groups array is empty no bundles will be created (and consequently the action won't be applied).