Free gift
How the free gift action works, what are the required and optional parameters to set it up, and the resources for which it's enabled
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):
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.
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):
"actions": [
{
"type": "free_gift",
"identifiers": {
"order.line_items.sku.id": [ "WKyPSgRwxY", "VCxRGsExyZ" ],
"order.line_items.bundle.id": [ "ABcDEfGhXy" ]
},
"quantity": 2
}
]Free promo detector
In terms of 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:
available_free_skus— the available SKUs eligible as free gifts once added to the order.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.
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:
order.line_items.sku.id
Matches line items by SKU ID (i.e. if the cart contains at least one of the SKU listed in the array).
order.line_items.bundle.id
Matches line items by bundle ID (i.e. if the cart contains at least one of the bundle listed in the array).
order.line_items.sku.sku_lists.id
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).
Only the three selector paths listed above are accepted as identifiers keys. Any other key will cause a validation error.
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:
Keys — identifier keys are processed in the order they appear in the
identifiersobject.IDs — within each key, IDs are processed in the order they appear in the array.
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.
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.
Restrictions
You cannot use bundles, aggregate targets, set a limit, target a specific attribute 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.
Resources
As regards the Rule Engine integration with Commerce Layer Core API, the percentage discount action type is available for promotions (order rules) only.
Last updated