# Bundle

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.

{% hint style="info" %}
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.
{% endhint %}

## 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](#sort) 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](#bundle-types).

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](#bundle-types) some restrictions may apply, for example:

* The list of required parameters may vary.
* Some optional key (e.g. value) may be available or not.

<table><thead><tr><th width="137">Key</th><th width="114">Type<select><option value="Djzo1UhBKQfW" label="Boolean" color="blue"></option><option value="VAIMp1rdLBI0" label="Integer" color="blue"></option><option value="qhaoRE82Rs3C" label="Float" color="blue"></option><option value="sk9tHN8WC8KO" label="String" color="blue"></option><option value="B3M67zaVXhvQ" label="Array" color="blue"></option><option value="MFocCrV7v0L6" label="Object" color="blue"></option></select></th><th width="338">Description</th><th>Example</th></tr></thead><tbody><tr><td><strong><code>type</code></strong></td><td><span data-option="sk9tHN8WC8KO">String</span></td><td>The bundle <a href="#bundle-types">type</a>. Can be one of <code>balanced</code> or <code>every</code>. Default is <code>balanced</code>.</td><td><code>"every"</code></td></tr><tr><td><strong><code>sort</code></strong></td><td><span data-option="MFocCrV7v0L6">Object</span></td><td>Additional information on how to sort the targeted items.</td><td>Learn more <a href="#sort">here</a>.</td></tr><tr><td><strong><code>value</code></strong></td><td><span data-option="VAIMp1rdLBI0">Integer</span></td><td>The number of items to be considered during the bundle calculation. Required for bundles of type <code>every</code>, cannot be set for bundles of type <code>balanced</code>.</td><td><code>2</code></td></tr></tbody></table>

## 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:

<table><thead><tr><th width="238">Key</th><th width="102">Type<select><option value="Djzo1UhBKQfW" label="Boolean" color="blue"></option><option value="VAIMp1rdLBI0" label="Integer" color="blue"></option><option value="qhaoRE82Rs3C" label="Float" color="blue"></option><option value="sk9tHN8WC8KO" label="String" color="blue"></option><option value="B3M67zaVXhvQ" label="Array" color="blue"></option><option value="MFocCrV7v0L6" label="Object" color="blue"></option></select></th><th width="109" data-type="checkbox">Required</th><th width="290">Description</th><th>Example</th></tr></thead><tbody><tr><td><strong><code>attribute</code></strong></td><td><span data-option="sk9tHN8WC8KO">String</span></td><td>true</td><td>The field of the resource specified in the action's selector on which to apply the bundle sorting. Works with numeric fields only.</td><td><code>"quantity"</code></td></tr><tr><td><strong><code>direction</code></strong></td><td><span data-option="sk9tHN8WC8KO">String</span></td><td>true</td><td>The type of sorting to apply on the targeted items before building the bundle. Can be one of <code>asc</code> or <code>desc</code>.</td><td><code>"asc"</code></td></tr></tbody></table>

{% hint style="info" %}
You can use bundles on [percentage](/rules-engine/actions/types/percentage.md), [fixed amount](/rules-engine/actions/types/fixed-amount.md), and [fixed price](/rules-engine/actions/types/fixed-price.md) actions only.
{% endhint %}

## 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:

<table><thead><tr><th width="177">Type</th><th width="116">Groups<select><option value="txUngB09I0fi" label="> 2" color="blue"></option><option value="2F1r71XQ9Rzo" label="1" color="blue"></option></select></th><th width="311">Description</th><th data-type="content-ref">Learn more</th></tr></thead><tbody><tr><td><code>balanced</code></td><td><span data-option="txUngB09I0fi">> 2</span></td><td>Ensures an even distribution of items across groups based on the sorting.</td><td><a href="/pages/OPJYHeHXECtWkNzcPAWn">/pages/OPJYHeHXECtWkNzcPAWn</a></td></tr><tr><td><code>every</code></td><td><span data-option="2F1r71XQ9Rzo">1</span></td><td>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.</td><td><a href="/pages/ITrvtso4AGc81hhlKJw3">/pages/ITrvtso4AGc81hhlKJw3</a></td></tr></tbody></table>

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.&#x20;
* **Every** — is more specific and works best for bulk discounts and progressive promotions depending on quantity multiples.

{% hint style="warning" %}
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).
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.commercelayer.io/rules-engine/actions/bundle.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.