# Buy X pay Y

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.

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

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).

{% hint style="info" %}
The action applies even when the quantity of the item isn't an *exact* multiple of X but just greater than.
{% endhint %}

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](#value) (for more information on the parameters listed in the table below and how they work please refer to the main [actions page](https://docs.commercelayer.io/rules-engine/actions)):

<table><thead><tr><th>Key</th><th>Type<select multiple><option value="YGgpISUGMdPQ" label="Boolean" color="blue"></option><option value="QePOb3JPIkBd" label="Integer" color="blue"></option><option value="rSmUinI3meTE" label="Float" color="blue"></option><option value="ytg3YoHxHpB2" label="String" color="blue"></option><option value="rlTqes6yAIME" label="Array" color="blue"></option><option value="qhQqnuEfMsvz" label="Object" color="blue"></option></select></th><th data-type="checkbox">Required</th><th>Notes</th></tr></thead><tbody><tr><td><strong><code>type</code></strong></td><td><span data-option="ytg3YoHxHpB2">String</span></td><td>true</td><td>Must be <code>"buy_x_pay_y"</code>.</td></tr><tr><td><strong><code>selector</code></strong></td><td><span data-option="ytg3YoHxHpB2">String</span></td><td>false</td><td></td></tr><tr><td><strong><code>identifier</code></strong></td><td><span data-option="ytg3YoHxHpB2">String</span></td><td>false</td><td>Can be set only if the <code>selector</code> key is defined and its value is an attribute.</td></tr><tr><td><strong><code>groups</code></strong></td><td><span data-option="rlTqes6yAIME">Array</span></td><td>false</td><td></td></tr><tr><td><strong><code>aggregation</code></strong></td><td><span data-option="qhQqnuEfMsvz">Object</span></td><td>false</td><td></td></tr><tr><td><strong><code>value</code></strong></td><td><span data-option="qhQqnuEfMsvz">Object</span></td><td>true</td><td></td></tr></tbody></table>

### Example

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

<pre class="language-json"><code class="lang-json">"actions": [
  {
<strong>    "type": "buy_x_pay_y",
</strong>    "groups": [ "discountable-items" ],
<strong>    "value": {
</strong><strong>      "x": 3,
</strong><strong>      "y": 2,
</strong><strong>      "result_item_limit": 1
</strong><strong>    },  
</strong>  }
]
</code></pre>

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:

<table><thead><tr><th width="238">Key</th><th width="145">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="115" data-type="checkbox">Required</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>x</code></strong></td><td><span data-option="VAIMp1rdLBI0">Integer</span></td><td>true</td><td>The base quantity, i.e. the number of units of the targeted item that qualifies for the discount (must be greater than the <code>y</code> key value).</td></tr><tr><td><strong><code>y</code></strong></td><td><span data-option="VAIMp1rdLBI0">Integer</span></td><td>true</td><td>The base number of items the customer is charged for, after meeting the base quantity condition (must be lower than the <code>x</code> key value).</td></tr><tr><td><strong><code>result_item_limit</code></strong></td><td><span data-option="VAIMp1rdLBI0">Integer</span></td><td>false</td><td>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).</td></tr></tbody></table>

## Restrictions

{% hint style="warning" %}
You cannot use [bundles](https://docs.commercelayer.io/rules-engine/actions/bundle), set a [limit](https://docs.commercelayer.io/rules-engine/actions/limit), or [target a specific attribute](https://docs.commercelayer.io/rules-engine/actions/..#apply-on) on which to apply the action when setting up every X discount Y actions.
{% endhint %}

## Resources

{% hint style="info" %}
As regards the Rule Engine [integration with Commerce Layer Core API](https://docs.commercelayer.io/rules-engine/readme#core-api-integration), the every X discount Y action type is available for [promotions](https://docs.commercelayer.io/rules-engine/resources/promotions) ([order rules](https://docs.commercelayer.io/rules-engine/core-api-integration/order-rules)) only.
{% endhint %}