Skip to main content

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 Offers are merchant-controlled promotions that surface alongside the trigger product on the product detail page (PDP) and inside the cart drawer / cart page. They’re powered by Shopify Functions — one Discount Function per offer type plus a shared Cart Transform Function — so the discount and the auto-added gift line both survive checkout authoritatively, even if the customer reloads the page or completes the order on a different device. Two offer types are supported. Both live in the same merchant dashboard, share the same display configuration, and use the same theme blocks — what changes is the trigger condition and how the discount/gift is applied.

​
The two offer types

Pick Offer (Buy X Get Y)

Trigger by a specific product or variant. When the customer adds X to their cart, they can pick 1+ items from a curated pool — each at a flat price, percent off, or fixed-amount off the regular price.

Free Gift (cart-value tiers)

Trigger by the cart’s subtotal crossing one or more thresholds. The gift variant is auto-added at €0 by the Cart Transform Function — no manual selection, no checkout step.
Each type registers as its own entry in the merchant dashboard’s Create offer flow:
  • Glood Pick Offer (Buy X Get Y)
  • Glood Free Gift

​
Pick offers

A pick offer says “buy this product, and you can add up to N items from this pool at a special price.”
SettingWhat it does
TriggerProduct- or variant-level. The offer surfaces only when the trigger appears on the PDP or in the cart.
PoolOne or more “slots.” Each slot is a pool of candidate products/variants the customer can pick from. The customer picks one from each slot.
PricingOffer-level default — flat price (e.g. +€1), percent off, or fixed-amount off. Each pool item can override the offer-level price.
Slot budgetslotsPerMainQty × mainQty, capped at maxSlots. A trigger added at qty=3 with slotsPerMainQty=1 unlocks 3 slots; the customer picks 3 gifts (one per main unit, or fewer).

​
What the customer sees

  • On the PDP — a panel below the price/description with the offer title, a slot meter (“1 / 2 Selected”), and gift cards rendered as checkboxes with thumbnails, prices, and qty steppers. Picks are committed to the cart together with the main product when the customer clicks Add to cart.
  • In the cart drawer / cart page — a collapsed “Add gifts” pill on the trigger line that expands into a swipeable carousel of pool items. A “Reselect” CTA on already-redeemed gift lines lets the customer swap one gift for another without leaving the drawer.

​
How the pricing is applied

The Glood Discount Function reads the cart-line attributes the storefront writes (__glood_uo_external_id, __glood_uo_role: 'pick', __glood_uo_slot_index) and applies the configured per-pool-item price. Each picked variant gets its own line in the cart with the adjusted price; the Cart Transform Function groups them visually under the trigger product so the customer sees a “bundle.”

​
Free-gift offers

A free-gift offer says “spend more, get this gift free.”
SettingWhat it does
TriggerCart subtotal crossing a configured threshold. Scope can be cart-wide or item-only (excludes shipping/tax).
TiersOne or more thresholds in ascending order. Each tier has its own gift variant.
Stackingcumulative (every qualifying tier grants its gift) or exclusive (only the highest qualifying tier wins; lower tiers’ gifts are swapped out as the customer crosses thresholds).
Eligibility exclusionsTag-based — exclude products by tag, or skip the cart subtotal contribution from already-discounted lines.

​
What the customer sees

The same theme block surfaces a multi-tier progress panel:
  • Locked tier — “Spend €X more to unlock {gift name}.”
  • Auto-added — the gift is qualified but the Cart Transform Function hasn’t injected the line yet (rare; sub-second).
  • ✓ In cart — the gift is in the cart at €0.
The customer never picks a free gift — once qualified, the Cart Transform Function injects the configured variant at price 0.00 directly into the cart, and the line stays as long as the subtotal stays above the tier’s threshold. Cross back below the threshold and the line is removed. For tiers configured with multiple variants (e.g., “free t-shirt — customer picks the size”), the panel renders a <select> + Add button instead of auto-adding; the customer commits the variant explicitly.

​
Where the offers surface

Both offer types use the same two theme blocks:
BlockWhere the merchant drops itWhat it renders
Glood Upsell for PDPProduct template — typically below the price/descriptionPick-offer panel, free-gift progress, slot meter, Add-to-cart-bundled commit
Glood Upsell for CartCart drawer section AND/OR /cart page sectionSame panels, scoped to the cart contents
Plus a mini-cart adapter — a single marker <div> per cart line lets the theme dev drop the carousel/CTA into ANY theme-owned cart drawer (Dawn, custom, hand-rolled). See the developer reference for the integration contract.

​
Enable Upsell Offers from the app embed

Even after the app is installed, the storefront upsell pipeline stays inert until the merchant flips one switch inside the Glood app embed. This single toggle controls whether glood-upsell.js, glood-upsell.css, the inline window.glood.upsell.* payload, and the gloodSwiper bundle get injected on every storefront page. With it off, no PDP panel, no mini-cart carousel, no free-gift progress — even if you’ve placed the theme blocks.

​
Step-by-step

  1. From your Shopify admin, go to Online Store → Themes.
  2. Find your live theme, click Customize to open the Theme Editor.
  3. In the bottom-left navigation, click Theme Settings.
  4. Select App embeds.
  5. Find Glood.AI Recommendations in the list and toggle it ON (if it isn’t already — this is the master switch for ALL Glood features).
  6. Click the embed name to expand its settings. Scroll to the Enable upsell offers checkbox and tick it.
  7. Click Save in the top right.
The Enable upsell offers checkbox is independent of the embed’s main ON/OFF toggle. The main toggle controls all Glood features (recommendations, search, bundles, upsell); the Enable upsell offers checkbox specifically gates the upsell asset bundle. Both must be on for the panels to render.

​
Verify the embed is active

After saving, visit any product page on your storefront and open DevTools → Console. Type: 
typeof window.glood?.upsell
  • Returns 'object' → the embed is loaded and the upsell payload is in place. Continue to “Quick activation” below to add the theme blocks.
  • Returns 'undefined' → the embed didn’t load. Re-check the toggle is ON and the Enable upsell offers checkbox is ticked, then hard-refresh (Cmd+Shift+R).
Full activation walkthrough with screenshots →

​
Quick activation

Once the embed is enabled, three more steps to a live offer:
  1. Install the app — the Cart Transform Function and Discount Functions deploy automatically.
  2. Drop the blocks — drag Glood Upsell for PDP into your product template and Glood Upsell for Cart into your cart drawer / cart page sections.
  3. Create the offer — in the Glood admin dashboard, create a Pick or Free Gift offer; assign trigger products / tier thresholds; save.
Once the embed is ON, the Enable upsell offers checkbox is ticked, the blocks are placed, and an active offer exists, the storefront panel renders automatically on any page where the trigger product is present.

​
How the pieces fit together

┌─────────────────────────────────────────────────────────────────────────────┐
│  Merchant dashboard                                                          │
│    ├─ Create / edit offer (pick or free_gift)                                │
│    └─ Push to storefront → product metafield (pick) OR shared metaobject     │
│                            (free_gift) consumed by app-embed.liquid           │
└──────────────────────────────────┬──────────────────────────────────────────┘
                                   │
                                   ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  Storefront (theme)                                                          │
│    ├─ app-embed.liquid emits window.glood.upsell.cartPickOffers + free-gift  │
│    │  payload, loads glood-upsell.js + glood-upsell.css                      │
│    ├─ Glood Upsell for PDP block — pick panel + free-gift progress           │
│    ├─ Glood Upsell for Cart block — same, scoped to cart                     │
│    └─ Mini-cart adapter — one marker <div> per cart line                     │
└──────────────────────────────────┬──────────────────────────────────────────┘
                                   │ /cart/add.js + /cart/change.js
                                   ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  Shopify cart                                                                │
│    ├─ Discount Function (upsell-offer-discount) — applies pick pricing       │
│    ├─ Discount Function (upsell-free-gift-discount) — applies 100% off       │
│    └─ Cart Transform Function — injects free-gift line + visually groups     │
│       picks into a "bundle" under the trigger product                        │
└─────────────────────────────────────────────────────────────────────────────┘
The contract is end-to-end authoritative: even if a customer bookmarks a cart URL with the pick gifts attached, the Discount Function re-validates server-side and only applies the configured pricing when the trigger condition still holds. Theme code can’t be manipulated to claim discounts the customer doesn’t qualify for.

​
Next steps