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.

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

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.

Last updated