Documentation Index
Fetch the complete documentation index at: https://docs.atomcommerce.io/llms.txt
Use this file to discover all available pages before exploring further.
This page covers setup and configuration for inline and accordion upsells — the messages that appear in the cart drawer or cart page. For the free shipping progress bar, see Free Shipping Bar.
All settings are in Online Store → Themes → Customize → Atom Commerce Connector.
Most stores only need these settings
To get upsells working, most stores only need to:
- Turn on Enable Upsells
- Choose Inline or Accordion layout
- Optionally customize the message text
- Optionally adjust the pill colors
Everything under Advanced theme placement and Custom theme selectors is for stores where upsells appear in the wrong position. Leave those sections alone unless something looks broken.
Basic setup
Enable upsells
Turn on Enable Upsells. Off by default.This enables upsell messages in both the cart drawer and cart page.
Customize messages (optional)
Set a Progress Message if you want something other than Atom’s default. Leave it blank to use the auto-generated message.See Message templates for ready-to-use examples. Style the pill (optional)
Under the inline pill color settings, adjust the background, border, and emphasis color to match your brand.The most impactful setting is Inline Pill Emphasis Text — the accent color on the key phrase like “2 more items”.
Which layout should I use?
| Layout | Choose when | What shoppers see |
|---|
| Inline | The offer relates to a specific product — Buy X Get Y, bundles, quantity-based deals | Message directly below the qualifying cart line |
| Accordion | Your store runs several offers at once, or you want all upsells grouped in one place | Collapsible section at the top of the cart |
Message templates
Atom generates a default message for each offer type. Use these as starting points for custom messages.
Buy X Get Y
Add **[PROGRESS_VALUE] more** to unlock [DISCOUNT]
Spend threshold
Spend **[AMOUNT] more** to unlock [DISCOUNT]
Next tier (tiered discounts)
Add **[PROGRESS_VALUE] more** to reach tier [NEXT_TIER] of [DISCOUNT]
Success message
Shown when the shopper qualifies. Only visible when Show Completed Upsells is on.
Shopper sees: You got Buy 3 Get 1 Free!
Message tokens
The two you need
For most offers, you only need:
| Token | Resolves to |
|---|
[PROGRESS_VALUE] | Remaining quantity or amount, chosen automatically based on offer type |
[DISCOUNT] | Offer name (e.g. “Buy 3 Get 1 Free”) |
[PROGRESS_VALUE] as your default. It formats as a quantity for item-based offers and a currency amount for spend-based offers — you don’t need to know which.
Emphasis styling
Wrap any text in **double asterisks** to highlight it in your accent color:
Add **[PROGRESS_VALUE] more** to get [DISCOUNT]
Without **...**, Atom auto-highlights the “N more” phrase in default server-generated messages:
Advanced tokens
Use these when you need precise control over the message format.
| Token | Resolves to | Use when |
|---|
[AMOUNT] | Currency amount remaining (e.g. “$15.00”) | Spend-based offers, when you specifically want the amount |
[QUANTITY] | Item count remaining (e.g. “2”) | Quantity-based offers, when you specifically want the count |
[CURRENT_TIER] | Current tier number | Tiered offers only |
[NEXT_TIER] | Next tier number | Tiered offers only |
Styling inline pills
These settings only apply when Upsell Layout Mode is Inline. Accordion upsells use your theme’s existing typography and colors.
Colors
The four color settings that matter most:
| Setting | Default | What it controls |
|---|
| Inline Pill Emphasis Text | #c1307a | The accent color on highlighted text — start here |
| Inline Pill Background | #f8f2f6 | Pill background fill |
| Inline Pill Border | #e7c2d8 | Pill border |
| Inline Pill Text | #3c3c3c | Regular message text |
Typography
| Setting | Default | Range | What it controls |
|---|
| Font Scale | 92% | 80–120% | Size relative to surrounding cart text — adjust this first |
| Font Size | 13 px | 11–18 px | Absolute size override |
| Font Weight | 500 | 300–900 | Weight for regular text |
Shape
| Setting | Default | Range |
|---|
| Border Width | 2 px | 0–6 px |
| Border Radius | 999 px (fully rounded) | 0–999 px |
Offer name
| Setting | Default | What it does |
|---|
| Show Offer Name In Inline Pill | Off | Prepends the offer title before the message |
| Bold Offer Name In Inline Pill | On | Bolds the offer title when shown |
Advanced theme placement
Most stores should leave these settings alone. Only change them if upsells are appearing in the wrong position. Incorrect values can prevent upsells from appearing entirely.
Cart row identity strategy
In inline mode, Atom matches each offer to the correct row in your cart’s HTML. The default works for most Shopify themes.
| Value | When to use |
|---|
| Line Item Key (default) | Most themes — Shopify’s standard row identifier |
| Variant ID | Theme doesn’t expose line keys on cart rows |
| Product Handle | Theme uses product handle as the row identifier |
| Title Fallback | Last resort — matches by visible product title |
Inline position
| Value | Description |
|---|
| Inside row footer (default) | Pill sits inside the row’s footer area |
| Between rows | Pill inserted as a separate element between rows |
Inline row placement
Only applies when Inline Position is Between rows.
| Value | Description |
|---|
| Below matched row (default) | Pill directly after the qualifying cart line |
| Above matched row | Pill directly before the qualifying cart line |
Cart drawer insert mode
Controls how accordion upsells attach to the drawer container.
| Value | Description |
|---|
| Default | Atom picks the insertion point automatically |
| Top of container | Prepended to the top of the drawer |
| Before target selector | Before a CSS selector you specify |
| After target selector | After a CSS selector you specify |
Custom theme selectors
Leave these blank unless you know what you’re doing. Incorrect selectors will stop upsells from appearing.
