App blocks overview
Understand the global App embed versus placeable app blocks, and where each Llama Upsell block is added in your theme.
Llama Upsell ships as a Shopify theme app extension. Its surfaces fall into two categories: a single global App embed that powers the cart and runtime, and a set of placeable app blocks you drop into specific sections of your storefront. Both are added through the Shopify theme editor — you never edit theme code by hand.
App embed vs. app blocks
The two block types serve very different roles.
The App embed (LC Upsell) targets the document head. It runs once per page, regardless of where you are in the store. It outputs the shared configuration the app needs — cart contents, customer context, currency, active campaigns, global styles, and subscription status — and it renders the Llama Cart. Because it targets head, it has no visible placement of its own; you toggle it on once from the theme editor's App embeds panel.
A placeable app block targets a section. Each instance is added inside a specific section of a template (for example, the product page or cart page) and renders an upsell offer at that exact spot. You can add multiple block instances across different templates, each pointing at a different campaign or widget.
The App embed must be enabled for the placeable blocks to work. The App embed supplies the shared runtime data (cart, customer, active campaigns, global settings) that every other block reads from.
Adding blocks in the theme editor
All Llama Upsell blocks are added from the Shopify theme editor — there is no manual Liquid editing required.
Open the theme editor
In your Shopify admin, go to Online Store → Themes, then click Customize on your active theme.
Enable the App embed
Open the App embeds panel and toggle on LC Upsell. This loads the app runtime and the Llama Cart across your storefront.
Add a placeable block
Navigate to the template where you want an offer (for example, the product page), then use Add block in the relevant section and choose the Llama Upsell block you need.
Configure and save
Set the block's options in the sidebar, then save. Settings update live in the editor preview.
All blocks at a glance
The table below lists every block in the extension, its purpose, and where it is typically placed.
| Block | Target | Purpose | Typically placed |
|---|---|---|---|
| App embed | head | Loads the app runtime and renders the Llama Cart for the whole store. | Enabled once from the App embeds panel. |
| Widget | section | The current, recommended block. Renders a Pre-Purchase or Gift with Purchase campaign and auto-selects its layout (slider, list, scrollable list, collapsible). | A section on the product, cart, or other template. |
| Slider | section | Deprecated. Shows upsell products in a horizontal carousel. | A section on the product or cart page. |
| List | section | Deprecated. Shows upsell products in a vertical list. | A section on the product or cart page. |
| Gift with purchase | section | Deprecated. Renders a Gift with Purchase campaign in a list, collapsible, slider, or modal layout. | A section on the product or cart page. |
The Slider, List, and Gift with purchase blocks are deprecated. Each is gated behind a deprecation flag and shows a "Deprecated block. Please, use Upsell Widget" notice in the editor. For new setups, use the Widget block, which covers the same campaign types with a single, configurable block.
How placeable blocks resolve a campaign
Every placeable block is tied to a campaign or widget. There are two ways the binding happens:
- Explicit ID — Set a Widget ID (Widget block) or Campaign ID (deprecated blocks) in the block settings. You find this ID in the Llama Upsell admin panel.
- Automatic — If you leave the Widget block's Widget ID empty, it falls back to an active campaign: an active Gift with Purchase campaign takes priority, otherwise an active Pre-Purchase campaign is used.
The block then reads that campaign's saved customization (layout, colors, content, and behavior) and renders the matching storefront experience.
Embed control
Most placeable blocks share an Embed control group. By default a block renders inline, exactly where you placed it in the section. When you enable Embed block, you can instead inject the rendered offer into a different element on the page using a CSS selector:
- Embed selector — the CSS selector of the target element (defaults to
body). - Placement — where to insert the block relative to that target: before the target, after the target, before its first child, or after its last child.
This lets you place an offer in a spot that is not exposed as a theme section block.
Subscription state is enforced at render time. If the app subscription limit has been reached, placeable widget offers are not rendered on the storefront.