> 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/skeleton/size-finder/free-gift.md).

# Free gift setup

Skeleton can automatically drop a free gift into the cart when a customer's spend crosses a threshold — with a second tier for bigger spenders, and a progress bar that shows how close they are. It's the "spend $100, get a free beanie" play, with no app subscription.

## ⚠️ Read this first: the gift must be priced $0

**The theme adds the gift to the cart — it cannot change the gift's price.** Themes aren't allowed to alter prices; only your product catalog and Shopify discounts can.

That means the gift product **must be priced $0.00 in your catalog**. If it isn't:

* The customer is **charged the real price at checkout**.
* The cart deliberately shows the real price instead of "FREE" — the theme refuses to display FREE on a line that actually costs money, so a misconfigured gift is at least honest, but it's still a broken promotion.

**The right way to set it up:** create a *separate, dedicated product* for the gift (e.g. "Free Beanie — Gift"), priced **$0.00**, and hide it from your catalog:

1. Go to **Products → Add product**. Name it clearly as the gift version.
2. Set the **Price** to `0`.
3. Under **Publishing**, keep the Online Store channel if you want its page reachable, or manage its visibility with your collections — the important part is that customers can't casually add a $0 product from your collections. The simplest guard: don't put it in any collection you display.
4. If you track inventory, give it stock — the auto-add only picks **in-stock** variants.
5. If the gift comes in sizes, add the size variants — the theme matches the gift's size to what's in the cart (more below).

💡 Why not a discount code instead? Codes can't auto-add products to the cart. This feature trades "the price says $0 in the catalog" for a completely automatic, no-code-needed experience.

## Tier setup walkthrough

The free gift is a **block on the Cart drawer section** — not a theme setting.

1. Open the theme editor: **Online Store → Themes → Customize**.
2. Click **Cart drawer** in the left panel.
3. Click **Add block → Free gift** (or click the existing Free gift block).
4. Configure:
   * **Enable free gift** — the master switch.
   * **Gift products from** — **Selected products** or **Collection (random pick)**.
   * **Gift products** — for Selected products: pick your $0 gift product(s). If you pick several, the first one whose size matches the cart is used.
   * **Gift collection** — for Collection: a random in-stock product from this collection is added. Every product in it must be priced $0.
   * **Tier 1 spend threshold** (default 100) — the cart subtotal (excluding gift lines) that unlocks the gift, in your store currency.
5. Optional second tier:
   * **Enable tier 2**, **Tier 2 spend threshold** (default 200), and its own **Tier 2 gift products** / **Tier 2 gift collection**. Tier 2 adds a *second* gift on top of tier 1 — a $250 cart with both tiers enabled carries two gifts.
6. Click **Save**, then test (checklist below).

💡 If you've enabled the block but picked no products, nothing auto-adds — in the editor you'll see a hint on the drawer reminding you to pick a gift.

## How the auto-add behaves

Understanding this saves you support emails:

* **Threshold math** — the qualifying spend is the cart subtotal **excluding gift lines**, using pre-discount line prices. The gift can't unlock itself.
* **Crossing up** — the moment qualifying spend reaches the threshold, the gift is added (quantity locked to 1).
* **Dropping down** — if the customer removes items and falls below the threshold, the gift is removed automatically.
* **Size matching** — if the gift has a size option, the theme picks the gift variant matching the most common size among the cart's items; if the cart's dominant size changes later, the gift swaps to match. No match available → first available variant.
* **Customer says no** — if the customer deletes the gift, it stays gone; it won't nag by re-adding itself unless their spend drops below the threshold and crosses it again (or they start a fresh cart).
* **Out of stock** — only in-stock variants are ever added; if every candidate fails, no gift appears.
* The cart line shows a **FREE** tag — but only when the line truly costs $0 (see the warning above).

## The milestone progress bar

The gift converts hardest when customers can *see* the gap. Pair the Free gift block with the **Milestone progress bar** block on the same Cart drawer section:

1. Still in the Cart drawer settings, click **Add block → Milestone progress bar** (if not already there).
2. Set a milestone to your gift: e.g. **Milestone 2 → Spend amount** = your tier 1 threshold, **Reward label** = "Free gift", **Icon** = Gift.
3. Use another milestone for free shipping (amount = your shipping threshold, icon = Shipping) and, if you run tier 2, the third milestone for it.
4. The **Progress text** ("Spend \[amount] more to unlock \[reward]") fills in the remaining amount and next reward automatically; **All unlocked text** shows once everything is passed.
5. Set an unused milestone's amount to **0** to hide it.

The bar measures the same qualifying spend as the gift logic (gift lines excluded), so the two always agree.

## Pre-launch test checklist

1. ⚠️ Open the gift product in your admin and confirm the price is **$0.00**.
2. On your storefront, add products worth just under the threshold — the bar should say "Spend $X more…".
3. Cross the threshold — the gift should appear within a moment, marked FREE, with the milestone pin checked.
4. Remove an item to fall below — the gift should disappear.
5. Cross again, then delete the gift yourself — it should stay deleted.
6. Go **all the way to checkout** and confirm the order total doesn't include the gift.


---

# 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/skeleton/size-finder/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.