> For the complete documentation index, see [llms.txt](https://sitesbyseth.gitbook.io/sitesbyseth-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sitesbyseth.gitbook.io/sitesbyseth-docs/showcase/free-gift.md).

# Free gift

Showcase can add a gift to the cart automatically when the buyer qualifies — by spending enough, by buying a specific product, or both. The theme handles the whole loop: a red gift tag on qualifying product names, a teaser and milestone in the cart, the automatic add when the condition is met, and the automatic removal if the cart drops below it.

## ⚠️ The one rule: price the gift at $0

Read this before enabling anything.

**The theme adds the gift product to the cart, but it cannot change prices.** Prices are checkout territory, and themes have no power there. So:

* If your gift product is priced **$0** in the catalog → the cart line says **Free**, checkout charges nothing. ✅
* If it's priced anything else → the theme still adds it, but the cart shows its **real price** and the customer **is charged for it at checkout**. The theme deliberately shows the real price rather than lying "FREE" over a paid line.

**Set it up the right way:**

1. Go to **Products → Add product** (or duplicate the giftable product).
2. Name it clearly — e.g. "Logo Beanie (Gift)" — and set the **price to 0**.
3. Make sure it's **active** and **in stock** (track inventory if quantities are limited — when it sells out, the whole gift feature pauses automatically).
4. Consider hiding it from search/collections so people don't "buy" it directly: remove it from collections and, if you use tags for collection rules, keep it untagged.

*Alternative:* keep the real price and create an **automatic discount** (Discounts → Amount off products) that zeroes exactly that product. This works, but the $0 duplicate product is simpler and impossible to misconfigure.

## Turning it on

1. **Customize → Theme settings → Free gift.**
2. Tick **Enable free gift**.
3. Pick the **Gift product** (the $0 one).
4. Choose **How the gift unlocks**:

   | Mode                          | The gift is added when…                                               |
   | ----------------------------- | --------------------------------------------------------------------- |
   | `Spend amount`                | the cart reaches the **Spend amount to unlock**                       |
   | `Buying a qualifying product` | any product from your **Qualifying products** list is in the cart     |
   | `Either one` (default)        | either condition is met                                               |
   | `Both required`               | the spend amount is reached *and* a qualifying product is in the cart |
5. Set the **Spend amount to unlock** (default 100, in your store currency) and/or pick up to 24 **Qualifying products**.
6. Optionally reword the **Gift tag text** (default `+ FREE GIFT`).

## What buyers see

* **On product screens** — a red **gift tag** next to the product name. On spend-based setups it appears on every product ("every purchase can earn this"); with a qualifying list, only those products carry the tag.
* **In the cart drawer** — if you've added the **Free gift block** ([Cart drawer](/sitesbyseth-docs/showcase/sections/cart-drawer.md)), a teaser row shows the locked gift with its unlock condition ("Unlocks at $100 — added automatically").
* **On the milestone bar** — if the **Milestone bar block** is present with **Show free gift milestone** on, a gift marker sits on the progress track at your spend threshold. (The marker only draws for spend-based modes — a "qualifying product only" gift has no spend threshold to mark.)
* **When they qualify** — the gift appears as its own cart line: gift tag, "Added automatically" note, price shown as **Free** (because it's $0, right?), quantity locked to 1, and no remove button.

## The fine print (how the logic protects you)

* **The gift can't unlock itself.** Progress toward the spend threshold ignores the gift line — even if the gift accidentally had a price, it wouldn't count toward its own unlock.
* **It's never the only thing in the cart.** If the buyer empties the cart, the gift goes too.
* **It self-corrects.** Drop below the threshold or remove the qualifying product, and the gift is removed automatically. Quantity is pinned to 1.
* **Sold-out gift = feature paused.** No teaser, no tags, no add attempts.
* All the pieces read from one place — **Theme settings → Free gift** — so the tags, teaser, milestone marker, and auto-add can never disagree with each other.

## Troubleshooting

* **"My customer was charged for the gift"** → the gift product isn't $0. Fix the price; the theme will show Free from then on.
* **"The gift milestone isn't on the bar"** → check: Milestone bar block added? **Show free gift milestone** on? Gift enabled and in stock? Unlock mode includes a spend amount above 0?
* **"The gift tag shows on every product"** → that's spend-mode behavior. Add a Qualifying products list (and use `Buying a qualifying product`, `Either one`, or `Both required`) to limit the tag to those products.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://sitesbyseth.gitbook.io/sitesbyseth-docs/showcase/free-gift.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.