Troubleshooting
Glossary
An A-Z reference of every Llama Upsells and Shopify term used across these docs, each with a plain-English definition and a link to its full guide.
This is the single alphabetized reference for every term you'll meet in the Llama Upsell & Cross-Sell docs — both our own app concepts and the Shopify platform concepts they sit on top of. Each entry gives a short, concrete definition and a link to the page that covers it in depth.
These terms are cross-linked throughout the docs: wherever a word from this glossary appears in another guide, it usually links straight to the page where that feature is configured. If a definition here feels too short, follow its link for the full walkthrough, settings, and edge cases.
How this page is organized
The glossary is split into three groups, each sorted A-Z:
- App concepts — features, settings, and objects you work with inside the Llama Upsells admin and theme editor.
- Shopify & platform concepts — terms that come from Shopify itself but directly affect how the app behaves.
- Things you might see but rarely touch — internal labels and developer hooks that surface in your store or theme, with a plain-English line so you know what they are.
Use your browser's find (Cmd/Ctrl+F) to jump to a term quickly.
App concepts
| Term | Definition | Learn more |
|---|---|---|
| App block / theme block | A widget you place into a section of your theme through the theme editor — for example a pre-purchase slider or a Gift with Purchase list. Each block points at one campaign and renders that campaign's offer where you drop it. | Widgets & Llama Cart |
| App embed | The single global theme block that loads the app's storefront runtime on every page. It runs as a headless orchestrator — it does no visible rendering itself, but it fetches the cart, applies Auto-Add logic, watches for cart changes, and syncs applied discount codes. Without the app embed turned on, nothing the app does appears on your storefront — no widgets, no auto-adds, no drawer. | Install and enable the app |
| Auto-Add | A campaign type that automatically puts a product into the shopper's cart (often a free gift) the moment the cart matches your rules, and removes it again if the cart stops matching. Auto-adds are handled by the app embed (not the Llama Cart drawer), so they run whether or not the drawer is open. Because adding a product changes the live cart, an Auto-Add can re-trigger other subtotal- or quantity-based campaigns. If multiple Auto-Add campaigns qualify, all of their products are added — there is no priority order between them. | Auto-Add campaign |
| Automatic (product) discount | The discount the app attaches to the products a campaign offers. It is implemented as a native Shopify automatic discount and applies only to the products added from that campaign's offer, not to the rest of the cart. | Applying discounts |
| BOGO | "Buy One Get One" — a promotion pattern, not a distinct campaign type. You build it with an Auto-Add campaign (add a free or discounted second unit when a qualifying product is in the cart) or with an offer discount on a Pre-purchase or GWP campaign. | Auto-Add campaign |
| Campaign | The core unit of the app: one offer plus the rules, targeting, and customization that decide when and where it shows. Each campaign has a single funnel type (Auto-Add, Pre-purchase, GWP, and so on). | Campaigns overview |
| Campaign health / status | The state shown next to each campaign on the dashboard. Active means the campaign is live and eligible to display; Inactive means it is turned off and will not show; Draft means it is still being built and has never been activated. A campaign can also display a red health warning when something blocks it from running. | Campaign statuses, limits & health |
| Cart Experience Variant | An app embed setting that controls which version of the Llama Cart shoppers see: Published (live for everyone), Test A / B / C (preview an alternate design for testing), or Disable (turn the drawer off). | Theme compatibility & cart type |
| Cart restriction | A rule that blocks or warns shoppers at the cart and/or checkout stage when the cart matches your conditions — for example, enforcing a minimum order value. Restrictions are enforced later than campaigns, so they can block a cart a campaign created. | Cart restrictions |
| Checkout upsell | A campaign type (Shopify Plus only) that shows product offers directly inside the Shopify checkout page using a Checkout UI extension. | Checkout Upsells |
| Condition | A group of rules attached to a campaign that decides whether the offer shows, evaluated against the live cart. A campaign can have multiple conditions, and each holds one or more rule groups. | How conditions work |
| Content Unlock | The Unlock campaign type — it hides exclusive products and reveals them only once the cart meets your unlock rules, usually shown with a progress bar toward a spend threshold. | Campaigns overview |
| Funnel type | The kind of campaign you're building, chosen when you create it. Options are Pre-purchase, Auto-Add, Gift with Purchase, Post-purchase, Checkout upsell, and Unlock. The funnel type determines where and how the offer appears. | Campaigns overview |
| Gift with Purchase (GWP) | A campaign type that offers a free or discounted gift when the cart meets your rules. Unlike Auto-Add, shoppers usually pick the gift from a widget you place on the page or in the cart. | Free Gift with Purchase |
| Llama Cart | The app's slide-out cart drawer. It replaces or supplements your theme's cart, can host campaign blocks, progress bars, and express payment buttons, and is loaded by the app embed. | Widgets & Llama Cart |
| Offer | The product (or set of products) a campaign presents to the shopper, together with any attached discount. | Applying discounts |
| Post-purchase | A campaign type that shows a one-click upsell on a dedicated page after the shopper pays but before the thank-you page. Post-purchase is the only funnel type with strict priority ordering — offers are shown one at a time, highest priority first. | Post-Purchase campaign |
| Pre-purchase | A campaign type that shows an offer before checkout — on the product page, cart, or anywhere you place its widget. Pre-purchase widgets only show products with a fully active storefront status. | Campaigns overview |
| Product limiter | A rule that caps how many of a product, variant, or SKU a shopper can have, enforced at checkout. Limits can be set per product, per variant, or per SKU, with the most specific level taking priority. | Products limiter |
| Rule / rule group / connector | A rule is a single test, such as "cart subtotal greater than $50." Rules are grouped into rule groups, and a connector (AND / OR) decides whether all rules or any rule must pass. Connectors join rules within a group and groups within a condition. | How conditions work |
| Setup Guide | The button in the campaign editor that walks you through placing the campaign's widget on your storefront. It must be completed once per campaign so the widget lands on the correct page. | Why a widget is not showing |
| Shipping discount | A discount type that offers free or reduced-cost shipping automatically at checkout when the cart meets your conditions. It runs independently of campaign and tier discounts. | Shipping discounts |
| Sync action | The Sync button on a campaign that forces the app to re-push its rules to Shopify metafields immediately. Use it when the storefront or checkout is showing out-of-date rules after a change. | Why changes take time to appear |
| Targeting filters | The campaign-level filters — schedule (date range), markets, and customer tags — that gate a campaign before its conditions are even checked. Within a campaign these are evaluated in order: date, then market, then customer tag, then condition rules. | Schedule, market & customer-tag targeting |
| Theme App Extension (TAE) | Shopify's name for the storefront layer that renders the app's widgets and Llama Cart. The app embed and every app block belong to this extension; it is the bridge between your theme and the app's runtime. | Theme compatibility & cart type |
| Tier discount | A "buy more, save more" volume discount that rewards a bigger discount as the cart subtotal grows. It applies to the overall cart and runs independently of campaign and shipping discounts. | Tier (volume) discounts |
Shopify & platform concepts
These are Shopify's own terms, but each one changes how the app behaves, so it's worth knowing them.
| Term | Definition | Learn more |
|---|---|---|
| Cart type (Drawer / Pop-up / Page) | How your theme presents the cart: a slide-out Drawer, a Pop-up modal, or a dedicated cart Page. Your cart type affects where widgets and the Llama Cart can appear and which behaviors are available. | Theme compatibility & cart type |
| Checkout UI Extension | The Shopify mechanism that lets the app render content inside the checkout page. It powers Checkout upsell campaigns and checkout-stage restriction messages, and is available only on Shopify Plus. | Checkout Upsells |
| Customer tags | Labels Shopify stores on customer accounts. The app can target campaigns to (or away from) shoppers with specific tags, optionally requiring the shopper to be logged in. | Market & customer-tag targeting |
| Discount combination rules / stacking | Shopify's own settings on each discount that decide whether it can combine with other product, order, or shipping discounts. The app does not override these — whether an app discount stacks with a Shopify code depends on each discount's combination settings. | Combining with Shopify discounts |
| Discount node | A Shopify object that holds an automatic discount and the metafield the app's discount Function reads. The app may create several of these for its product discounts (see the "DO NOT MODIFY" entry below). | Metafields (developers) |
| Dynamic Checkout / Buy it Now / accelerated checkout | Shopify's express buttons (Shop Pay, Apple Pay, Google Pay, PayPal, "Buy it Now") that skip the cart and jump straight to payment. Because they bypass the cart, they change which cart-stage features get a chance to run. | Restrictions & limiters with express checkout |
| Markets | Shopify's system for selling to different countries or regions, each with its own currency and pricing. The app can target campaigns to specific markets, and a campaign with no market list runs for all markets. | Market & customer-tag targeting |
| Metafield | A key-value field Shopify stores on a resource such as the shop or a discount node. The app saves its campaign, discount, restriction, and limiter rules into metafields so checkout extensions can read them without calling the app's server. | The campaign storage limit |
| Metafield character limit (10,000) | Shopify caps each function-accessible metafield value at 10,000 characters. The app compresses its data to fit (typically a 40-60% reduction) and leaves a safety margin, packing discount data up to 9,990 characters per node before splitting. The admin warns you as you approach the limit; exceeding it can stop some campaigns from displaying. | The campaign storage limit |
| Online Store 2.0 (OS 2.0) | Shopify's modern theme architecture that supports app blocks via JSON templates. The app's widgets and Llama Cart require an OS 2.0-compatible theme. The app evaluates every non-demo theme and grades it as full, partial, or unsupported; only your published (main) theme with full or partial support counts as the "supported main theme." | Theme compatibility & cart type |
| Presentment currency / presentment currency rate | The currency a shopper actually sees (their market's currency) and the exchange rate Shopify uses to convert your store's base prices into it. Money-based rules must account for conversion, which is a common source of "why didn't my rule fire" confusion. | Multi-currency & markets gotchas |
| Proxy server / rate limiting (429) | Every storefront request the app makes goes through Shopify's App Proxy (the /apps/upsell/ path) rather than directly to the app's backend, and many responses are cached for about 5 minutes. If too many requests arrive at once, the proxy can return a rate-limit response (HTTP 429) and the call is retried — usually invisible to shoppers, but worth knowing when diagnosing delays. | Why changes take time to appear |
| Promo-code trigger | A campaign condition that fires when a shopper applies a specific discount code. These are evaluated on the app's server (not the storefront widget), so the code text never appears in your page source and there's a brief delay before the campaign shows. | Promo-code triggers |
| Shadow DOM | A browser feature the app uses to render each visible widget in an isolated container, with its own styles injected directly into that container. This is why widgets ignore your theme's CSS — and why theme styles can't accidentally break them. To restyle a widget, use the app's customizer or its custom CSS field instead of your theme stylesheet. | Customizing appearance |
| Shop Pay | Shopify's accelerated one-click checkout. Like other express buttons, it can skip the cart, which affects when cart-stage features run. | Restrictions & limiters with express checkout |
| Shopify Function / WASM extension | Small programs that run on Shopify's servers at checkout to apply discounts and validations without calling an external server. The app's product, tier, and shipping discounts plus its restrictions and limiters all run as Functions, reading their config from metafields. | Metafields (developers) |
templates/cart.json | The OS 2.0 template file that defines your cart page's sections and blocks. The app reads it during onboarding and looks for an apps-type section containing a block that references the app (shopify://apps/lc-upsell-and-cross-sell). The result is reported as Installed, Not installed (supported theme but block missing), or Not supported (theme lacks OS 2.0), which drives the onboarding prompts. | Theme compatibility & cart type |
| Unlisted product | A Shopify product that is published to your store but hidden from search and collection pages. Auto-Add, Gift with Purchase, and Post-purchase can offer unlisted products; Pre-purchase and checkout upsell cannot. | How features interact |
| Vintage theme | A theme built on Shopify's older (pre-OS 2.0) architecture. Vintage themes don't support app blocks, so widget placement is limited and the app grades them as unsupported or partial. | Theme compatibility & cart type |
Things you might see but rarely touch
These are internal labels and developer hooks. You don't configure them directly, but you may run into them in your Shopify admin or theme code, so here's what they mean.
A note on overlapping terms
A few terms describe the same thing at different layers, and it helps to keep them straight:
- App embed, Theme App Extension, and app block are nested ideas: the Theme App Extension is the whole storefront layer Shopify gives the app; the app embed is the one global block that loads its runtime; and an app block is any individual widget you place from that extension.
- Auto-Add, GWP, Unlock, Pre-purchase, Post-purchase, and Checkout upsell are all funnel types — different flavors of campaign. (BOGO is not a funnel type — it's a pattern you build, usually with Auto-Add.)
- Tier discount, shipping discount, and the automatic (product) discount on a campaign are three separate discount features that run independently and can all apply to one order.
If a guide uses a term you don't recognize, it's almost certainly defined above — and linked to its full page.
Related
How features interact
The order features run in and what overrides what when campaigns, discounts, restrictions, and limiters overlap.
Theme compatibility & cart type
Whether your theme supports the app, how OS 2.0 grading works, and how your cart type changes behavior.
The campaign storage limit
The 10,000-character metafield cap that can silently stop campaigns from reaching your storefront.
Metafields (developers)
The lc_upsell metafield namespace and how the discount Function reads it.