Buy X pay Y

How the buy X pay Y action works, what are the required and optional parameters to set it up, and the resources for which it's enabled

Actions of type buy_x_pay_y enable you to offer your customer a very common promotion according to which if the quantity of the selected items (or the condition's matchers if the selector is not specified) is a multiple of X, only a number of units equal to the same multiple of Y are considered for the total price computation.

If none of the targeted items satisfy the minimum requirements for the action to apply (i.e. their quantity is less than X), the action won't have any effect.

Basically, if an item has a quantity equal to any multiple m of the x attribute, a discount is applied as if the purchased quantity of the same item was decreased down to the same multiple of the y attribute (where x must be greater than y and m greater than zero).

The action applies even when the quantity of the item isn't an exact multiple of X but just greater than.

This way, customers that add to cart n units of a specific product (where n is greater than or equal to m*x and less than (m+1)*x) pay only for m*y+(n-m*x) = n-m*(x-y) units of the same product, thus getting m*(x-y) units for free

When setting up a buy X pay Y action, in addition to the action type, you need to specify at least the x and y values within the value object as described here (for more information on the parameters listed in the table below and how they work please refer to the main actions page):

Key	Type	Required	Notes
type	String		Must be "buy_x_pay_y".
selector	String
identifier	String		Can be set only if the selector key is defined and its value is an attribute.
groups	Array
aggregation	Object
value	Object

Example

The following action applies a 3x2 promotion only to one of the related condition's matchers grouped as discountable-items:

"actions": [
  {
    "type": "buy_x_pay_y",
    "groups": [ "discountable-items" ],
    "value": {
      "x": 3,
      "y": 2,
      "result_item_limit": 1
    },  
  }
]

Considering some real number:

• If the quantity of the targeted item is 3, the customer will pay only for 2 units of that item, getting 1 unit for free.

• If the quantity of the targeted item is 6, the customer will pay only for 4 units of that item, getting 2 units for free.

• If the quantity of the targeted item is 7, the customer will pay only for 5 units of that item, getting 2 units for free.

• If the quantity of the targeted item is 11, the customer will pay only for 8 units of that item, getting 3 units for free.

Value

The x and y values of a buy X pay Y are defined within the value object where you can also optionally set a limit on the number of items to consider for the calculation:

Key	Type	Required	Description
x	Integer		The base quantity, i.e. the number of units of the targeted item that qualifies for the discount (must be greater than the y key value).
y	Integer		The base number of items the customer is charged for, after meeting the base quantity condition (must be lower than the x key value).
result_item_limit	Integer		The maximum number of items that will be considered among the eligible ones to apply the action (based on the order in which they appear within the payload against which the rule is checked).

Restrictions

You cannot use bundles, set a limit, or target a specific attribute on which to apply the action when setting up every X discount Y actions.

Resources

As regards the Rule Engine integration with Commerce Layer Core API, the every X discount Y action type is available for promotions (order rules) only.