Every

How bundles based on quantity multiples work

This alternative bundling strategy maximizes the number of items picked from the targeted group (listed according to the desired sorting logic) ensuring that it is equal to or a multiple of a specified number.

Bundles of type every can be created only from one group containing at least one item. If the related actions.groups array is made by more than one group, the Rule Engine will return an error. If the specified group is empty, the action won't be applied.

Key	Type	Required	Notes
type	String		Must be "every".
sort	Object		Learn more here.
value	Integer

How the every algorithm works

1. The items of the targeted group are sorted according to the sort.direction function applied to the sort.attribute numeric field.

2. The total quantity of units within the group is calculated by adding up the quantities of each item: Q = q1 + q2 + ... + qn

3. Being M the maximum multiple of the number V specified in the bundle's value key that doesn't exceed the total quantity Q, the number of units that won't be discounted X is calculated by subtracting M from Q: X = Q - M = Q mod V

4. Starting from the bottom of the ordered list generated by the sorting, a quantity of units equal to X is removed to get the final list of items that will be discounted.

If the number specified in the value key is already a multiple of the total quantity (i.e. M = Q and consequently X = 0), the action will be applied to all the items of the group.

If some items of the group match the bundle's sort.direction function with the same numeric value of the field specified in the sort.attribute value, they will be sorted as they are listed in the payload against which the rule is evaluated.

Example

Let's assume that a rule's conditions define the discountable-items group of line items as follows:

[
  {
    "id": "qOYocnANsO",
    "type": "line_items",
    "quantity": 2,
    "unit_amount_cents": 2000,
    "total_amount_cents": 4000,
    "sku": {
      "id": "PeHfayCvwQ",
      "code": "HAT"
    }
  },
  {
    "id": "nlHjpkVpCG",
    "type": "line_items",
    "quantity": 3,
    "unit_amount_cents": 1000,
    "total_amount_cents": 3000,
    "sku": {
      "id": "pHaoUAvTVy",
      "code": "STICKER"
    }
  },
  {
    "id": "DtZjSMEKvm",
    "type": "line_items",
    "quantity": 2,
    "unit_amount_cents": 3000,
    "total_amount_cents": 6000,
    "sku": {
      "id": "TkhHRotCOA",
      "code": "TSHIRT"
    }
  }
]

Let's consider the following action that applies a 10% discount to the group above. The discount will be applied to bundles built by picking the items 2 at a time and prioritizing the ones with higher unit amounts:

"actions": [
  {
    "type": "percentage",
    "selector": "order.line_items.sku",
    "groups": [ "discountable-items" ],
    "bundle": {
      "type": "every",
      "sort": {
        "attribute": "unit_amount_cents",
        "direction": "desc"
      }
      "value": 2
    },
    "value": 0.1
  }
]

1. Sorting

The items of the group are sorted based on their unit amount, from the highest to the lowest:

Item	Quantity	Unit amount
TSHIRT	2	3000
HAT	2	2000
STICKER	3	1000

2. Total quantity of units

The total quantity of units within the group is Q = 2 + 3 + 2 = 7.

3. Number of units to be removed

Being the number of the bundle.value key 2, the number of units to be removed is calculated as the remainder of the division between the total quantity and the value: 7 mod 2 = 1.

4. Items to be discounted

One item will be removed starting from the bottom of the ordered list (i.e. one sticker), thus getting to the final outcome, resulting in a 10% discount applied to 2x bundles, not to the additional item with lower unit price:

SKU	Quantity	Discounted unit amount
TSHIRT	2	5400
HAT	2	3600
STICKER	2	1800