Skip to main content
The Auto-Add Free Product Discount feature enables you to set free products to be automatically added to a shopper’s cart if they meet certain criteria, instead of requiring that shopper to go and search for the product when they become eligible for it.

​
Use Cases

​
Auto-Add Gift Card

You create a discount in which the condition is product A and the target is a $25 gift card. You select the auto-add free product discount type in the Discounts page. The gift card is automatically added to the end consumer’s cart when they add Product A to their cart.

​
Multiple Auto-Add Discounts Applying to Same Target Product

You create two discounts:
  1. Buy Product A, get Product B for free
  2. Buy Product A, get Product C for free
Where:
  1. Adds Product A (quantity 1) to their cart. The system determines which free product is the better deal to the consumer and adds it to the cart as part of the winning discount. If Product B and C are considered the same value, the system uses the first discount run and adds that target product to the cart.
  2. Adds two copies of Product A to their cart and one of your discounts has a max redemption of 1 set. If the better deal is the discount with the max redemption, both discounts can be applied, giving the shopper both Product B and C for free. If the better deal is not the discount with the max redemption, then the shopper will receive the same target product with each copy of Product A.
  3. Adds two copies of Product A to their cart and both of your discounts have a max redemption of 1 set. The shopper receives both Product B and C.

​
Effect on Discounts

​
Auto-Add Discount Competing with Other Line Item Discounts

When applying an auto-add discount and a line item product discount to the same target product, the system selects the discount that provides the best deal for the shopper after the free product is added to the cart. If the system does not choose the auto-add discount, the free product returns to full price, remains in the cart, and must be removed by the shopper.

​
Auto-Add Free Products without Setting a Condition

Discounts with or without coupon codes must have any other product in cart before the free product is auto-added to cart. For example, if the shopper has a coupon code for a free product but no items currently in their cart, the shopper must add an item first, and then enter the coupon code to receive the free product.

​
Removing and Re-Adding Free Products from Cart

If the shopper removes the free target item from cart, the item will no longer be auto-added. However, if the shopper manually re adds the free target item manually, they will again see the item as free.

​
Enable the Auto-Add Free Product Discounts Feature

This feature requires changes to your core theme. Ask your theme developer to make the required changes to your theme to enable this feature, as detailed in the following GitHub pull requests:

​
Set Up Auto-Add Target Discounts

To set up a discount to auto-add free products:
  1. Go to Marketing > Discounts in Admin.
  2. Select either an existing discount or Create Discount.
  3. Set the Applies To field to Line Item and the Affects field to Product. This enables you to view the Auto Add Free Product option in the Type field.
  4. Set the Type field to Auto Add Free Product.

​
Headless and Custom Storefront Implementation

The platform does not add the free product to the cart by itself. Instead, it signals eligibility via a suggestedDiscounts array on the Cart object. Your storefront is responsible for reading this signal and acting on it. Storefronts built on the Kibo Core Theme have this logic built in. Headless and custom storefronts must implement it manually using the steps below.

​
How It Works

Every time the cart is modified (item added, updated, or removed), Kibo re-evaluates all active discounts and updates the suggestedDiscounts array on the cart. Each entry in this array tells your storefront whether a free product should be added, and how.

​
The suggestedDiscounts Object

{
  "suggestedDiscounts": [
    {
      "discountId": 1001,
      "productCode": "FREE-WIDGET",
      "autoAdd": true,
      "hasMultipleProducts": false,
      "hasOptions": false
    }
  ]
}
FieldDescription
discountIdThe ID of the discount driving this suggestion
productCodeThe product code of the free item to be added
autoAddtrue = add silently without shopper interaction. false = shopper input required, or item was previously rejected
hasMultipleProductstrue = multiple free products are eligible; shopper must choose one
hasOptionstrue = the free product has configurable variants; shopper must select options

​
Step 1 — Mutate the Cart

When the shopper adds, updates, or removes a cart item, call the appropriate endpoint: 
POST   /api/commerce/carts/current/items       (add item)
PUT    /api/commerce/carts/current/items/{id}  (update item)
DELETE /api/commerce/carts/current/items/{id}  (remove item)
These endpoints return the individual CartItem that was added or updated — they do not return the full cart object. You must make a follow-up call (Step 2) to check for suggested discounts.

​
Step 2 — Fetch the Full Cart

After every cart mutation, immediately call: 
GET /api/commerce/carts/current
This returns the full Cart object, including the suggestedDiscounts array. Example response: 
{
  "id": "cart-abc-123",
  "items": [...],
  "suggestedDiscounts": [
    {
      "discountId": 1001,
      "productCode": "FREE-WIDGET",
      "autoAdd": true,
      "hasMultipleProducts": false,
      "hasOptions": false
    }
  ],
  "rejectedDiscounts": []
}

​
Step 3 — Evaluate Each suggestedDiscount Entry

Loop through each entry in suggestedDiscounts and apply the following logic.

​
Case 1: autoAdd: true — Silently Add the Free Product

When autoAdd is true and both hasMultipleProducts and hasOptions are false, add the free item to the cart automatically without any shopper interaction. Call: 
POST /api/commerce/carts/current/items
Request body: 
{
  "product": {
    "productCode": "FREE-WIDGET"
  },
  "quantity": 1,
  "autoAddDiscountId": 1001
}
autoAddDiscountId is required. Setting this field tells the platform this item was added as part of a discount. Without it, the platform will not be able to automatically remove the free item if the qualifying product is later removed from the cart, and shopper rejection will not be tracked correctly. Example pseudocode: 
for (const suggestion of cart.suggestedDiscounts) {
  if (suggestion.autoAdd && !suggestion.hasMultipleProducts && !suggestion.hasOptions) {
    await addCartItem({
      product: { productCode: suggestion.productCode },
      quantity: 1,
      autoAddDiscountId: suggestion.discountId
    });
  }
}

​
Case 2: hasMultipleProducts: true — Show a Product Selection Modal

When multiple products are eligible as the free gift, the shopper must choose one. Display a modal or UI component listing the eligible products. Once the shopper selects a product, add it: 
{
  "product": {
    "productCode": "WIDGET-GREEN"
  },
  "quantity": 1,
  "autoAddDiscountId": 1001
}

​
Case 3: hasOptions: true — Show a Variant/Configurator Modal

When the free product has required options (e.g. size, color), the shopper must select them before the item can be added. Display a product configurator or variant picker. Once the shopper has selected their options, add the fully configured item: 
{
  "product": {
    "productCode": "FREE-WIDGET",
    "options": [
      { "attributeFQN": "tenant~size", "value": "L" },
      { "attributeFQN": "tenant~color", "value": "Blue" }
    ]
  },
  "quantity": 1,
  "autoAddDiscountId": 1001
}

​
Case 4: autoAdd: false with No Other Flags — Shopper Previously Rejected

If autoAdd is false and neither hasMultipleProducts nor hasOptions is true, the shopper has already explicitly removed the free item from their cart during this session. The platform tracks this in cart.rejectedDiscounts. Do not re-add the item or re-show the modal. Respect the shopper’s choice for the remainder of the session. 
// Do nothing — shopper already rejected this discount
if (!suggestion.autoAdd && !suggestion.hasMultipleProducts && !suggestion.hasOptions) {
  return;
}

​
Step 4 — Handle Qualifying Product Removal

If the shopper removes the product that qualified them for the discount, the platform will automatically remove the free item from the cart on the next re-price. When you call GET /api/commerce/carts/current after the removal, the free item will no longer appear in cart.items and suggestedDiscounts will be empty. No additional storefront action is required — simply re-render the cart from the response.

​
Complete Decision Flow

After every cart mutation → GET /api/commerce/carts/current
|
+-- for each entry in suggestedDiscounts:
      |
      +-- autoAdd: true, no other flags
      |     +-- Silently POST add free item (with autoAddDiscountId)
      |
      +-- hasMultipleProducts: true
      |     +-- Show product selection modal → POST add chosen item (with autoAddDiscountId)
      |
      +-- hasOptions: true
      |     +-- Show variant/configurator modal → POST add configured item (with autoAddDiscountId)
      |
      +-- autoAdd: false, no other flags
            +-- Shopper rejected — do nothing

​
Key Rules

RuleDetail
Always GET the full cart after mutationsPOST/PUT/DELETE /items returns a CartItem, not the full cart — suggestedDiscounts is only on GET /api/commerce/carts/current
Always set autoAddDiscountIdRequired when adding a free item so the platform can manage its lifecycle
Never re-add a rejected itemIf autoAdd: false with no other flags, the shopper removed it — honor that for the session
Qualifying item removed = free item removedThe platform handles this automatically — just re-render from the GET response
Re-check after every mutationsuggestedDiscounts is re-evaluated on every cart change — always check after add, update, and remove operations