# Free gift

Actions of type `free_gift` enable you to apply a 100% discount to specific line items that have been added to the cart as free gifts. Unlike other action types, they target line items directly by their IDs and the action distributes a discount budget across them in priority order.

When setting up a free gift action, in addition to the action `type`, you must specify which line items are eligible via the `identifiers` object and optionally cap the total number of discounted units via the `quantity` key (for more information on any 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>"free_gift"</code>.</td></tr><tr><td><strong><code>identifiers</code></strong></td><td><span data-option="qhQqnuEfMsvz">Object</span></td><td>true</td><td>Learn more <a href="#identifiers">here</a>.</td></tr><tr><td><strong><code>quantity</code></strong></td><td><span data-option="QePOb3JPIkBd">Integer</span></td><td>false</td><td>Learn more <a href="#quantity">here</a>.</td></tr></tbody></table>

{% hint style="warning" %}
The free gift action does not use a `selector` or a `value` field. The discount is always 100% and is applied automatically and the only allowed selector is `order.line_items`. Including these two keys in the action payload will cause a validation error.
{% endhint %}

### Example

The following action applies a 100% discount to up to 2 units of line items matching any of the provided SKU or bundle list identifiers (i.e. if the cart contains the SKUs identified by the `WKyPSgRwxY` or `VCxRGsExyZ` IDs, or the bundle identified by the `ABcDEfGhXy` ID):

<pre class="language-json"><code class="lang-json">"actions": [
  {
<strong>    "type": "free_gift",
</strong><strong>    "identifiers": {
</strong>      "order.line_items.sku.id": [ "WKyPSgRwxY", "VCxRGsExyZ" ],
      "order.line_items.bundle.id": [ "ABcDEfGhXy" ]
    },
<strong>    "quantity": 2
</strong>  }
]
</code></pre>

{% hint style="success" %}

## Free promo detector

In terms of [Core API integration](https://docs.commercelayer.io/rules-engine/core-api-integration), when a flex promotion with a free gift action is active and its conditions are met, Commerce Layer populates two dedicated relationships on the [order object](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/orders/object):

* `available_free_skus` — the available SKUs eligible as free gifts once added to the order.&#x20;
* `available_free_bundles` — the available bundles eligible as free gifts once added to the order.

You can use these relationships on the frontend to present the customer with a list of possible free gifts during checkout — for example, surfacing an "add your free gift" prompt that lets them pick and add an eligible item directly from the list. A common pattern is to check available free SKUs and bundles at cart load time and render a gift selection UI whenever either list is non-empty — without requiring the customer to know in advance which products qualify.
{% endhint %}

## Identifiers

The `identifiers` object maps selector paths keys to arrays of IDs values. Any line item matching at least one selector / ID pair becomes eligible for the free gift discount. At least one key must be present, and each value must be a non-empty array of strings.

The currently allowed selector paths are:

<table><thead><tr><th width="308.28515625">Key</th><th width="107.1875">Type<select><option value="QEbry2ZnzBz5" label="Integer" color="blue"></option><option value="gOpyXJAF5ut7" label="Float" color="blue"></option><option value="zKBBDSWTPKCq" label="String" color="blue"></option><option value="7XqoKWpURzPW" label="Array" color="blue"></option><option value="TA0Av7eIcDbC" label="Object" color="blue"></option></select></th><th>Description</th></tr></thead><tbody><tr><td><strong><code>order.line_items.sku.id</code></strong></td><td><span data-option="7XqoKWpURzPW">Array</span></td><td>Matches line items by SKU ID (i.e. if the cart contains at least one of the SKU listed in the array).</td></tr><tr><td><strong><code>order.line_items.bundle.id</code></strong></td><td><span data-option="7XqoKWpURzPW">Array</span></td><td>Matches line items by bundle ID (i.e. if the cart contains at least one of the bundle listed in the array).</td></tr><tr><td><strong><code>order.line_items.sku.sku_lists.id</code></strong></td><td><span data-option="7XqoKWpURzPW">Array</span></td><td>Matches line items by SKU list ID (i.e. if the cart contains at least one of the SKU belonging to the provided SKU lists).</td></tr></tbody></table>

{% hint style="warning" %}
Only the three selector paths listed above are accepted as `identifiers` keys. Any other key will cause a validation error.
{% endhint %}

## Quantity

The `quantity` parameter defines the total number of units that will receive a 100% discount, distributed across all matching line items. It defaults to `1` if not specified.

When multiple line items match, the engine assigns the discount budget in a fixed priority order based on:

1. **Keys** — identifier keys are processed in the order they appear in the `identifiers` object.
2. **IDs** — within each key, IDs are processed in the order they appear in the array.
3. **Line items** — when multiple line items match the same selector / ID pair, they are processed in the order they appear in the cart.

The budget is decremented as units are assigned. Once the full `quantity` value has been allocated, any remaining matching line items receive no discount.

{% hint style="info" %}
This parameter controls how many units receive the discount in total, not which items are eligible. For example, if `quantity` is `2` and three matching line items each have a quantity of `1`, only the first two in priority order will be discounted — the third won't.
{% endhint %}

## Restrictions

{% hint style="warning" %}
You cannot use [bundles](https://docs.commercelayer.io/rules-engine/actions/bundle), [aggregate](https://docs.commercelayer.io/rules-engine/actions/aggregation) targets, set a [limit](https://docs.commercelayer.io/rules-engine/actions/limit), [target a specific attribute](https://docs.commercelayer.io/rules-engine/actions/..#apply-on) on which to apply the action, or specify any key other than the ones listed in the table above when setting up free gift actions. These keys are not compatible with the free gift action and their presence will cause a validation error.
{% 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 percentage discount 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 %}