How Auto-Add adds & removes products
A deep dive into Auto-Add runtime behavior — the add/remove lifecycle, quantity caps, added-item memory, availability gating, and edge cases.
This page explains what an Auto-Add campaign actually does behind the scenes once it's live: when the free product appears, when it's pulled back out, why it sometimes doesn't come back after a shopper removes it, and how the app tells its own lines apart from the ones a shopper added. If you're just getting started, set the campaign up first in the Auto-Add campaign guide — this page assumes the campaign already exists and focuses on the runtime mechanics.
Everything below happens automatically in the cart. You don't configure any of it directly — it's the behavior you get once an Auto-Add campaign is active. Knowing how it works helps you predict what shoppers see and answer support questions.
The add/remove lifecycle
Auto-Add is not a one-time action. It's re-evaluated on every cart change. Each time the cart updates — a product added, a quantity changed, a line removed, a discount code entered — the app re-checks your campaign rules against the new cart and decides what to do:
- If the cart now matches the rule and the gift isn't already there, it adds the free product.
- If the cart no longer matches the rule, it removes the gift it previously added.
- If the gift is present but in the wrong quantity, it corrects the quantity (see One free item per campaign).
When the cart stops matching, the gift is removed
This is the part that surprises people most. The free product is conditional — it only belongs in the cart while the rule is satisfied. The moment the cart drops below the condition, the app pulls the gift back out.
Concretely, when a campaign's rule fails, the offered variant moves to an "unqualified" list, and the app finds the matching auto-added line and sets its quantity to 0 (which removes it).
Before — the rule matches
Your campaign offers a free tote when cart subtotal is greater than or equal to 100 USD. The shopper's cart subtotal is 120 USD. On the last cart update, the app added the free tote at a 100% discount. The cart now shows the paid items plus the free tote.
The shopper changes the cart
The shopper removes a 40 USD item. The cart subtotal drops to 80 USD. This triggers a cart-update, and Auto-Add re-evaluates.
After — the rule no longer matches
80 USD is below the 100 USD threshold, so the rule fails. The free tote is now "unqualified," and the app automatically removes it from the cart. The shopper is left with only their paid items.
A removed gift is expected behavior, not a bug. If a shopper (or a support agent) reports that "the free gift vanished," the first thing to check is whether the cart still meets the campaign's rule. Cross the threshold back up and the gift returns on the next cart update.
One free item per campaign, and the quantity cap
Each Auto-Add campaign gives one free item, and each qualified gift line carries a maximum quantity. The default maximum quantity is 1.
You can raise that ceiling per variant using the campaign's per-variant quantity setting. Whatever value you set there becomes the maximum quantity stamped onto the auto-added line and the quantity it's added at.
| Behavior | Value | Notes |
|---|---|---|
| Default maximum quantity per gift line | 1 | Applied when no per-variant quantity is set. |
| Quantity the gift is added at | The maximum quantity | The line is created at the cap, not at 1, when a higher cap is configured. |
| Raise the cap | Per-variant quantity setting | Lets you give, for example, 2 free units instead of 1. |
The app forces the quantity back down
Because the gift is free, a shopper might try to bump its quantity up manually to get more free units. Auto-Add prevents this. On every cart update, if it finds an auto-added line whose quantity is above its maximum quantity, it resets that line back down to the maximum.
So if the cap is 1 and a shopper edits the free line to quantity 3, the next cart update silently snaps it back to 1. The shopper never keeps extra free units.
The app only forces down, never up. If a shopper lowers an auto-added line below the cap, the app leaves it alone — it won't push the quantity back up.
Why it's free — the 100% discount
The "free" part isn't a price of zero typed onto the product. Each qualified gift is added through a 100% discount tied to the campaign, so the line item's price is fully discounted at checkout. The product is a normal cart line; the discount is what zeroes out its cost. This is why the gift behaves like any other line in the cart (it can be removed, its quantity shows, and so on) while still costing nothing.
Added-item memory — why a removed gift doesn't keep reappearing
If the app only checked "is the gift in the cart?", a shopper who deleted the free product would see it instantly re-added on the next cart update — an annoying loop. To avoid that, Auto-Add remembers which variants it has already auto-added.
The app keeps a small record of added gift variant IDs in the browser. When deciding whether to add a gift, it checks two things:
- Is the gift already in the cart for this campaign?
- Has this variant been auto-added before (per the memory record)?
It only adds the gift when both are false — the gift isn't in the cart and it hasn't been auto-added before in this session.
Why the gift didn't come back after I removed it. If a shopper manually deletes the free product while the cart still matches the rule, the app does not re-add it. The memory record says "already added this," so it leaves the shopper's decision alone. This is intentional — shoppers who don't want the freebie shouldn't have to fight the cart.
What resets the memory
The one thing that clears the memory is an empty cart. When the cart has fewer than 1 item, the app wipes its added-item record. The next time the cart qualifies, the gift is treated as brand new and can be added again.
Because the record lives in the browser session, it also clears naturally when the session ends. The practical rule of thumb: empty the cart to "reset" Auto-Add for a shopper who removed the gift but now wants it back.
Quick reference: will the gift be (re)added?
| Situation | Gift added? |
|---|---|
| Cart matches the rule, gift not in cart, never auto-added this session | Yes |
| Cart matches, gift already in cart | No (already there) |
| Cart matches, shopper deleted the gift, memory still holds the record | No (respects removal) |
| Cart emptied, then re-qualified | Yes (memory was reset) |
| Cart no longer matches the rule | No — and any existing gift is removed |
Line item properties — how the app knows its own lines
When Auto-Add creates a gift line, it stamps several hidden line item properties onto it. These are invisible to the shopper but let the app identify which cart lines it owns versus lines the shopper added themselves. The app never touches shopper-added lines.
| Property | What it holds |
|---|---|
Condition ID (_lcu_condition_id) | The specific rule/condition that qualified this gift. Used to match the line back to its campaign condition. |
| Campaign ID | The campaign that added the line. |
| Auto-Add widget ID | Marks the line as one created by Auto-Add. The app uses the presence of this property to recognize its own lines. |
| Maximum quantity | The quantity cap for this line, used to enforce the quantity cap. |
The widget ID property is the key marker. When the app needs to remove a gift or correct its quantity, it only acts on lines that carry this property. A line without it is treated as shopper-owned and is left untouched — even if it happens to be the same product as the gift.
The condition ID matters when you run more than one Auto-Add campaign. The app matches a gift line by both its variant and its condition ID, so two different campaigns offering overlapping products each keep their own separate line.
Availability gating — sold-out gifts are skipped
Before adding a gift, Auto-Add runs a live availability check against your store. It queries each candidate variant's real-time stock status and skips any variant that isn't available for sale.
- If a gift variant is sold out, it's filtered out and not added.
- If all of a campaign's candidate gift variants are unavailable, nothing is added — the app logs that all auto-add products are unavailable and moves on.
- This ties directly into the Hide out of stock behavior; out-of-stock products don't get offered. See Hide out of stock in Llama Cart features.
If a gift suddenly stops appearing for everyone, check the gift product's inventory. A sold-out variant is silently skipped — there's no error shown to the shopper. Restock it (or pick an in-stock variant) and the gift starts appearing again.
Llama Cart vs Checkout
Auto-Add operates in two places, and the runtime behavior is consistent across both:
In the Llama Cart, Auto-Add reacts to cart-update events as the shopper browses and edits their cart. Adds, removals, and quantity corrections happen as described above, on every cart change.
On the Checkout page, Auto-Add runs through the checkout app block. This requires the Allow app to block checkout option to be enabled so the app can adjust the cart at checkout. See the setup steps in the Auto-Add campaign guide. Without this option, the checkout-side behavior can't run.
Rapid cart changes are de-duplicated
When a shopper makes several quick changes in a row, multiple cart-update events can fire before the first add finishes. To avoid double-adding the same gift, Auto-Add tracks in-flight adds: a gift that's currently being added is marked as "processing" and won't be queued a second time until that add completes.
This dedup is matched by both variant and condition ID, so it's specific to a single campaign's gift. Two genuinely different gifts from two campaigns can still be added in the same burst — only true duplicates are suppressed.
Edge cases & recipes
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Gift never appears | Cart doesn't meet the rule, or the gift variant is sold out | Verify the rule is satisfied; check the gift's inventory. |
| Gift disappeared mid-session | Cart dropped below the rule | Bring the cart back above the threshold/condition. |
| Removed gift won't come back | Added-item memory still holds the record | Empty the cart to reset, then re-qualify. |
| Shopper has extra free units | They raised the quantity manually | The next cart update resets it to the maximum quantity automatically. |
| Gift missing only at checkout | Allow app to block checkout not enabled | Enable it in checkout settings — see the setup guide. |