Checkout Upsells in depth
How the in-checkout widget behaves live, its display modes and customization, variety limits, the four checkout blocks, and edge cases.
This is the companion to the Checkout Upsells setup guide. That page walks through creating the campaign — choosing your offer and your display triggers. This page explains what the widget actually does once it is live in checkout: how it reacts to the cart in real time, the display modes and customization settings you can tune, how variety limits disable add buttons, the four checkout blocks the app installs, and the edge cases that trip merchants up.
You don't configure most of the runtime behavior below directly — it's what you get once a Checkout Upsells campaign is live and the app block is on your checkout. Knowing how it works helps you predict what shoppers see and answer support questions. For the two-step creation flow and the offer-mode tables (AI Recommendations vs Manual Products List), see the setup guide.
How the checkout widget behaves live
The Checkout Upsells widget is not a static banner. It continuously re-validates your campaign's display conditions against the current checkout cart and shows or hides offers as that cart changes. Every time the cart updates — an item added, removed, a quantity changed, or a promo code applied — the widget re-checks your rules and recalculates which offers qualify.
Because of this, the set of offers a shopper sees in checkout is live:
- If the cart now matches a condition, the widget shows that condition's offer products.
- If the cart stops matching, the offer products for that condition disappear from the widget.
- If an offer item the shopper already added is no longer valid (its condition stopped matching), the app automatically removes it from the cart — see Variety limits & disabled add buttons.
Shoppers interact with offers directly inside checkout. From the widget they can:
- Add an offer item to the cart.
- Remove an offer item they previously added.
- Change the quantity of an offer item (when the quantity selector is enabled).
- Switch the variant of an offer item (when the variant selector is enabled).
Why the Continue button pauses for a moment
While the app is updating the cart or re-validating conditions, checkout progress is briefly blocked. This is a deliberate "buyer-journey intercept": the app holds the Continue button for a moment so the shopper can't advance to the next checkout step in the middle of a cart change. It prevents race conditions — for example, completing the order before an offer item finishes being added, or before an invalid item finishes being removed.
The pause happens whenever any of the following is in progress:
- The cart is being updated (an add, remove, or quantity change is in flight).
- Conditions are being re-validated against the new cart.
- Campaign or product data is still loading.
- Offer discounts are still loading.
A short pause on Continue right after a shopper adds, removes, or changes an upsell item is expected behavior, not a bug. The button releases as soon as the cart update and validation finish (typically a fraction of a second). If shoppers report Continue being stuck for longer, it usually points to a slow network or a data-loading issue rather than the intercept itself — try the checkout again on a stable connection.
Display modes
The widget supports two layouts for presenting offers. You pick one in the campaign customizer (see Widget customization settings).
| Mode | What it does | Default |
|---|---|---|
| List | All offer products render together inside a single scrollable container with a maximum height of about 400px. Shoppers scroll within the widget to see more offers. | No |
| Paginate | One product per "page," with previous / next controls to move between offers. Only one offer is visible at a time. | Yes |
When to use each
List mode works well when you want shoppers to see several offers at a glance and quickly skim them. Because all offers share one scrollable box capped at roughly 400px, a long list stays compact and doesn't push the checkout layout down the page. Best for a small-to-medium set of related add-ons where browsing is part of the appeal.
Paginate mode shows one product at a time with previous/next controls. Use it when each offer deserves full attention — a single hero add-on, a warranty, or a premium upgrade — or when you'd rather shoppers consider offers one by one instead of scanning a list. It keeps the widget's footprint to a single product card regardless of how many offers qualify.
Widget customization settings
The widget's appearance and labels are configured in the campaign customizer (in the app), not in the Shopify checkout editor. The customizer settings are bound to the on-checkout block through a Widget ID: the checkout block carries a Widget ID setting, and the app matches it to your campaign's customization. (This is also how the block knows which campaign to render — there is one Widget ID text field on the Checkout Upsells block.)
| Setting | What it controls |
|---|---|
| Title text | The heading shown above the offers. |
| Title size | The font size of the heading. |
| Title color | The color of the heading text. |
| Title alignment | How the heading is aligned (for example, left/center). |
| Add button label | The text on the button used to add an offer to the cart. |
| Added button label | The text shown once an offer has been added. |
| Remove button label | The text on the button used to remove an added offer. |
| Variant selector visibility | Whether shoppers can choose a different variant of an offer item in the widget. |
| Quantity selector visibility | Whether shoppers can change the quantity of an offer item in the widget. |
| Display mode | List or Paginate — see Display modes. |
Because customization is bound by Widget ID, the block on your checkout doesn't need any styling configuration of its own — its only meaningful setting is the Widget ID. Change the look, labels, or display mode in the campaign customizer and the live checkout widget updates to match.
Variety limits & disabled add buttons
Each display condition can cap how many distinct offer items a shopper may add — this is the per-condition variety limit. (In Manual Products List mode, each product row also shows a Limit, as described in the setup guide.) The widget enforces the cap live:
- Once a condition's variety limit is reached, the remaining offer items for that condition show a disabled add button — the shopper can't add more distinct items beyond the cap.
- Those capped items are sorted to the end of the list, so the items a shopper can still add stay at the top where they're most visible.
- If conditions stop matching, any invalid upsell items are automatically removed from the cart. The widget keeps the cart consistent with the rules — an offer item that no longer qualifies doesn't linger in checkout.
A greyed-out add button on some offers is the variety limit doing its job, not a glitch. The shopper has already added as many distinct items as that condition allows. To free up a slot, the shopper removes one of the items they already added; the disabled buttons become active again on the next update. If you want shoppers to be able to add more distinct items, raise the limit on the condition in the campaign.
An upsell item vanishing from the cart in checkout is expected when its condition stops matching — for example, the shopper removed the product that qualified the offer. The app removes the now-invalid item to keep the order consistent with your rules. Bring the cart back to a qualifying state and the offer reappears in the widget so it can be re-added.
The four checkout blocks
The Checkout Upsells extension registers four checkout blocks. Knowing what each one does helps when you're adding blocks in the Shopify checkout editor.
| Block | What it is | Visible to shoppers? |
|---|---|---|
| Checkout Upsells (widget) | The upsell widget that shows offer products and the add / added / remove actions. | Yes — this is the only block that shows products. |
| Auto Add Product (checkout embed) | An invisible block that runs Auto-Add and Gift-with-Purchase logic at checkout. It renders no UI. | No (invisible). |
| Invalid Promo Code Banner | An error banner shown below the discounts section when an applied promo code is invalid. | Yes (only when there's an error). |
| Checkout Promotional Image | A configurable promotional image block. | Yes (the image). |
Only the Checkout Upsells widget block shows offer products. The Auto Add embed is invisible by design, the Invalid Promo Code Banner appears only when a code is rejected, and the Promotional Image block displays a static image. If you've added a checkout block but see no products, confirm you added the Checkout Upsells widget — not one of the other three.
Promotional Image block settings
The Promotional Image block is a simple, configurable image with no campaign logic. You set it up entirely in the Shopify checkout editor. Every setting:
| Setting | Type | Options / values | What it does |
|---|---|---|---|
| Promotional Image URL | Text | Any image URL | The image to display in checkout. |
| Promotional Image Alt Text | Text | Accessibility description | Alt text for the image (for screen readers and when the image can't load). |
| Padding | Choice | none, extraTight, tight, base, loose, extraLoose | Space around the image. |
| Border Radius | Choice | none, base, small, large, fullyRounded | How rounded the image corners are. |
| Loading | Choice | eager, lazy | When the image loads — eager loads immediately, lazy defers until it's near view. |
| Fit | Choice | cover, contain | How the image fills its box — cover fills and may crop, contain fits the whole image. |
| Position | Choice | start, center, end | How the image is positioned within its box. |
| Max Width | Integer | Pixels | Maximum width of the image. |
| Max Height | Integer | Pixels | Maximum height of the image. |
Always set Alt Text. It's read by screen readers and shown if the image fails to load — leaving it blank hurts accessibility and gives shoppers no fallback context.
Specific-country trigger
Checkout Upsells supports a display trigger that's exclusive to this campaign type: Specific Country. It shows the upsell only to shoppers in the countries you select (or excludes specific countries). Because checkout is where the shopper's shipping country is known, this rule is available here in addition to all the standard condition rules. See the setup guide's Display triggers section for where to set it.
Edge cases & recipes
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| No upsell widget in checkout | The Checkout Upsells block isn't added to the checkout layout | Add the Checkout Upsells block in Settings → Checkout → Customize. |
| Widget shows in standard checkout but not Shop Pay | The per-block Shop Pay option is off | Enable Include block in Shop Pay — see the Shop Pay guide. |
| Block added but no products show | You added a different block (Auto Add, banner, or image) | Confirm it's the Checkout Upsells widget block — only that block shows products. |
| Some add buttons are greyed out | The condition's variety limit is reached | Remove an added item, or raise the condition's limit. |
| An offer item was removed mid-checkout | Its condition stopped matching | Return the cart to a qualifying state; the offer reappears. |
| Continue button pauses briefly | Buyer-journey intercept during a cart update / validation | Expected — it releases when the update finishes. |
| Looking for in-checkout auto-add | Discontinued Feb 1, 2025 | Use the Auto-Add campaign. |
Related
Checkout Upsells (Shopify Plus)
Show product offers directly inside the Shopify checkout page. Requires Shopify Plus, and learn how to configure it.
Managing multiple offers
Add, rename, switch between, and delete several offers inside a single campaign to build tiered promotions without extra campaigns.