Cart Controls

1. Purpose

Cart Controls let shoppers edit an item without leaving checkout. Instead of abandoning the checkout to fix a wrong size, color, or quantity, the customer clicks a Modify link under the cart line and adjusts the item in a quick modal — changing the variant, updating the quantity, or removing the item entirely. Fewer trips back to the cart means fewer abandoned checkouts.

Cart Controls is one of the app's per-line cart components, added to a cart line in the checkout editor alongside Cartline Upsell, Auto Add to Cart, Badge, Review, and Custom Text Line.

2. What the Shopper Sees

A Modify link appears below the cart line item in the checkout cart summary. Clicking it opens a modal containing:

Product image — a square preview of the selected variant.
Price — the current variant price, shown in a success (green) tone.
Variant selectors — cascading dropdowns for each product option (e.g. Size, Color), shown only when variant change is enabled.
Quantity stepper — a number field with +/− buttons (minimum 1).
Stock warning — "This variant is currently out of stock" if the chosen combination is unavailable.
Update button — applies the variant and/or quantity change.
Remove button — removes the item entirely (shown only when enabled).

All changes update the cart in real time. If something goes wrong, the modal shows a clear message such as "Could not update this item. Please try again."

3. Shopper Actions

From the modify modal a customer can:

Switch variant — pick a different size, color, or other option combination.
Change quantity — increase or decrease the number of units.
Remove the item — delete the cart line completely.

Variant dropdowns are inventory-aware: out-of-stock options are grayed out, and changing one option (e.g. Size) intelligently resets the others to an available choice.

4. Merchant Configuration

When you select a Controls block in the checkout editor, the right panel exposes these settings:

Block name — internal reference label (default "Controls"). For internal reference only. Required.
Modify button text — the label for the link shoppers click (default "Modify").
Modal heading — the title at the top of the modal. Leave blank to use the product title.
Allow variant change — Let shoppers switch the variant from the modify modal. On by default.
Allow remove — Show a Remove button in the modify modal. On by default.
Display — optional conditional visibility rules (see §6).

The Update, Remove, and Quantity labels inside the modal default to "Update", "Remove", and "Quantity".

5. How to Add Cart Controls

Open the Checkout editor in the app.
Go to the cart summary section where cart line items are shown.
On a cart line, click Add element.
In the picker, choose Controls (alongside Cartline upsell, Auto add to cart, Badge, Review, and Custom text line).
The block is added to the cart line and shows a Modify preview.
Click the block to open its configuration form in the right panel.
Set the button text, modal heading, and toggle Allow variant change / Allow remove.
Optionally add Display conditions to control when it appears.
Changes save automatically.

Note: you can add one Controls block per cart line. Controls renders last, below any Review, Custom Text, Badge, Upsell, and Auto Add elements on the same line.

6. Display Conditions

The Display section lets you decide when the Modify link appears, using the app's condition builder (AND logic). Use it to, for example, show controls only for certain products, collections, or cart states. Leave it empty to always show the control.

Cart Controls works alongside the other per-line components, all added from the same Add element picker:

Auto Add to Cart — automatically adds a product when a condition is met. Controls lets shoppers adjust or remove those auto-added items. (Auto-added items use a restricted variant list so shoppers can only swap to allowed variants.)
Cartline Upsell — suggests related products with "+ Add" buttons. Upsell brings in new items; Controls edits items already in the cart.
Badge — labels an item (e.g. "Auto Added", "Best Seller"). Often paired with Controls.
Review — shows product reviews under the line.
Custom Text Line — renders custom text/metafield content under the line.

8. Common Use Cases

Reduce checkout abandonment — let shoppers fix a wrong size/color in place instead of going back to the cart.
Quantity adjustments — allow last-minute quantity changes without leaving checkout.
Manage auto-added items — give shoppers a clean way to swap or remove products added by Auto Add to Cart.
Streamlined edits — pair with Badges so special items are both labeled and editable.

9. Best Practices

Reduce checkout abandonment — let shoppers fix a wrong size/color in place instead of going back to the cart.
Quantity adjustments — allow last-minute quantity changes without leaving checkout.
Manage auto-added items — give shoppers a clean way to swap or remove products added by Auto Add to Cart.
Streamlined edits — pair with Badges so special items are both labeled and editable.

10. Common Mistakes to Avoid

❌ Adding more than one Controls block per line — only one is supported per cart line.
❌ Disabling variant change on option-heavy products — shoppers then can't fix the exact problem Controls is meant to solve.
❌ Overwriting the modal heading unnecessarily — leaving it blank keeps the product title, which is usually clearest.
❌ Forgetting to test out-of-stock combinations — confirm the stock warning appears and the Update button behaves correctly.

11. Troubleshooting

Modify link not showing: Confirm the Controls block is added to the cart line, the block is active, and any Display conditions are satisfied.

Variant selectors missing: Ensure Allow variant change is enabled and the product has more than one variant.

No Remove button: Check that Allow remove is enabled.

Update/Remove fails: The modal shows "Could not update this item…" / "Could not remove this item…" — retry; if it persists, verify the variant is in stock and the cart line is still valid.

Out-of-stock variant can't be selected: This is expected — unavailable combinations are grayed out and blocked with a stock warning.

12. Summary

Cart Controls give shoppers a fast, in-checkout way to edit variant, change quantity, or remove an item through a Modify modal — cutting the round-trips that lead to abandoned checkouts. Add it per cart line from the Add element picker, set the button text and modal heading, toggle Allow variant change and Allow remove, and optionally scope it with Display conditions. It pairs naturally with Auto Add to Cart, Upsell, and Badges to give each cart line a complete, editable experience.