> ## Documentation Index
> Fetch the complete documentation index at: https://docs.glood.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Upsell Promotions

> Drive AOV with two new promotion types — Product Upsell (Buy X Get Y) and Free Gift on cart value — surfaced on PDP and in the cart drawer.

Glood **Upsell Promotions** add two merchant-controlled promotion types to your store that live on the PDP and inside the cart drawer / cart page. Both are powered by Shopify Functions (one Discount Function per type plus a shared Cart Transform Function), so the discount and gift logic survive checkout authoritatively.

## The two promotion types

<CardGroup cols={2}>
  <Card title="Product Upsell (Buy X Get Y)" icon="cart-plus" iconType="duotone">
    Trigger by a specific product. When a customer buys X, they can add 1+ pool items (Y) at a configured price: flat price, percent off, or a fixed amount off. Per-pool-item pricing overrides supported.
  </Card>

  <Card title="Free Gift (cart-value tiers)" icon="ribbon" iconType="duotone">
    Trigger by cart subtotal crossing one or more thresholds. The chosen gift variant is auto-added to the cart at €0 by the Cart Transform Function — no manual checkout step.
  </Card>
</CardGroup>

Each promotion type registers as its own entry in Shopify's "Select discount type" modal so the merchant always knows which one they're creating:

* **Glood Product Upsell (Buy X Get Y)** — pick offers
* **Glood Free Gift** — cart-value tier offers

## What the customer sees

### On the product page

When a merchant has placed the **Glood Upsell for PDP** theme block:

* **Title + subtitle** describing the offer (e.g. "+€1 Add-On Gifts — Choose premium accessories for just €1 with your NAS purchase").
* **Slot meter** — "You have **1** add-on gift slot." | "**1 / 1** Selected" — adapts live as the customer changes the main-product quantity (slot count = `slotsPerMainQty × qty`, capped at `maxSlots`).
* **Pool item cards** — checkbox + thumbnail + product name + price (struck-through compare price). The selected card expands to reveal a quantity stepper and, if the product has multiple variants, a variant selector.
* **Free-gift section** — one panel per active free-gift offer (highest priority wins if multiple exist). Each tier renders as a card with three states:
  * **Locked** — "Spend €X more to unlock"
  * **Auto-added** (eligible, server-side Cart Transform pending)
  * **✓ In cart** (gift line confirmed present)

### In the cart drawer / cart page

The **Glood Upsell for Cart** block surfaces:

* Free-gift progress and "Auto-added" / "✓ In cart" states (same as PDP).
* Pick offers triggered by the current cart contents but not yet redeemed ("Complete your order with…").

## How offers are wired

| Layer                     | Pick offer (Buy X Get Y)                                                      | Free-gift offer (cart-value)                                                 |
| ------------------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Shopify Discount Function | `upsell-offer-discount` — applies per-pool-item pricing                       | `upsell-free-gift-discount` — applies 100% off on auto-injected gift line    |
| Cart Transform Function   | —                                                                             | `upsell-cart-transform` — injects the gift variant at \$0 when threshold met |
| Storefront-readable data  | `product.metafields.glood.upsell_pick_offers` (json, on each trigger product) | `shop.metaobjects.glood.values` filtered by `key == 'upsell_free_gift'`      |

The canonical JSON shape is the same across admin API, Shopify metafields, and the storefront blocks — see `web/backend/common/services/upsellOfferDiscount.js#toCanonicalPayload` in the app codebase.

## Setup

1. Install the Glood app and ensure your plan includes the **Upsell Promotions** feature.
2. From the Glood admin → **Upsell Offers** → create a pick or free-gift offer. Save and set status to **Active**.
3. In the Shopify theme editor:
   * Open a product template → click your product-info section → **Add block** → search **"Glood Upsell for PDP"** → drag under the description.
   * Open the cart-drawer section (and/or `/cart` page section) → **Add block** → search **"Glood Upsell for Cart"** → drop in.
4. Visit a triggering product page or add a triggering product to the cart — the block renders the offer.

<Note>
  Shopify's Cart Transform Function requires at least one **existing cart line** to anchor the injected gift. Configure free-gift offers with `minSubtotal > 0` so the customer has added something before they qualify.
</Note>

## Multi-tier free gifts

Free-gift offers support either **cumulative** or **exclusive** tier stacking:

* **Cumulative** — every qualifying tier grants its reward. Customer crossing €50 and €100 thresholds gets both gifts.
* **Exclusive** — only the highest qualifying tier grants its reward. Customer crossing both thresholds gets only the €100 gift.

Set the mode in the Glood admin per offer.

## Combinations with other discounts

Each promotion's `combinesWith` flags map directly to Shopify's discount-stacking model:

| Glood admin field                        | Shopify `combinesWith.*`                                                             |
| ---------------------------------------- | ------------------------------------------------------------------------------------ |
| Combine with other Glood offers          | `productDiscounts: true` (lets multiple Glood offer lines coexist)                   |
| Combine with Shopify automatic discounts | `productDiscounts / orderDiscounts: true`                                            |
| Combine with Shopify discount codes      | `productDiscounts: true` (Shopify's automatic-vs-code rule lets a code stack on top) |

## Next steps

<Card title="Theme integration & JS hooks" icon="code" href="/for-developers/upsell-blocks-integration">
  Wire the block into custom themes, integrate the native variant + quantity selectors, and use the `window.Glood.upsell` pub/sub bus to react to selections, qty changes, and cart updates from your own theme code.
</Card>