How do blocks work?

Your cart’s layout is a stack of blocks: configurable pieces you add, reorder, style, and customize in the cart editor. Which blocks you include, and in what order, is the cart shoppers see. For how blocks sit inside states and sections, see How do carts work?.

​

Blocks and sub-blocks

There are two kinds of block:

• Blocks sit directly in the cart, in one of three sections: Header, Body, or Footer. Each section offers a different set of blocks.
• Sub-blocks nest inside another block. Today only Cart items hosts sub-blocks: the Product row (the line-item row itself), Subscription upgrade, and Custom code.

​

Adding, reordering, and removing blocks

• Add a block with the Add block picker. A block is greyed out if it can’t go where you’re adding it, or if you’ve reached its limit (the picker shows a count/max badge).
• Reorder by dragging a block within its section.
• Remove with the trash icon, except locked blocks (below).
• Show/hide most blocks with the eye toggle, which hides a block from shoppers without deleting it. A few structural blocks can’t be hidden: Cart items, Checkout button, and the Product row.

​

Locked blocks

Some blocks can be reordered but not deleted, so core cart behavior (for example, checking out) can’t be removed by accident:

• Cart items
• Checkout button

​

Default blocks

New carts start with a working default layout:

• Filled cart: Header, Banner, Cart items, Summary, Checkout button
• Empty cart: Header, Empty cart block

​

How many of each block you can add

Limits are counted per cart state, not per cart. The filled cart and the empty cart each get their own allowance, so a cart can hold three Banners in its filled layout and three more in its empty layout. Most blocks are limited to one per state. The exceptions:

​

Content, Design, and Code

Each block is configured through up to three surfaces in the editor:

• Content: the block’s settings (text, product choices, thresholds, and so on). The Custom code block is the one exception: it has no Content panel because the block is the code.
• Design: per-block styling that layers on top of your global Design settings. Every block has one except Custom code, which has no settings panel at all.
• Code: override the block’s built-in rendering with a custom template. Most blocks support this; a couple don’t.

​

Show or hide by market, country, or currency

Some blocks can show different settings, or hide entirely, based on who the buyer is. That is separate from the sidebar eye toggle, which turns a block on or off for everyone. Supported condition types today: Shopify market, customer country, and customer currency (each with In or Not in). Cart total and cart contents are not condition types. Use Rewards tier thresholds for spend/quantity progress, or the Cart SDK when you need a rule the editor can’t express. Conditions are an ordered list: the first matching condition wins. Put specific rules above an All buyers catch-all. If nothing matches, the block renders nothing for that shopper. In the editor today, the full Conditions UI ships on the Rewards block: different tier sets per market, country, or currency. Other blocks either use a single “all buyers” configuration or don’t participate in this system yet. Editor preview does not evaluate the live buyer. Select a condition in the panel to preview that variant.

​

All blocks

Structure

• Header: title, item count, logo, and close control, pinned to the top.
• Cart items: the items customers add to cart; repeats per line.
• Subscription upgrade: sub-block that offers to convert a line to a subscription.
• Summary: totals, savings, and applied discounts.
• Checkout button: the primary call-to-action to checkout.
• Empty cart: the content shown when the cart is empty.
• Express payments: accelerated checkout buttons (Shop Pay, PayPal, and so on) inside the cart.

Merchandising

• Upsells: strategy-picked product recommendations.
• Product add-on: a single specific product offered as an add-on.
• Rewards: tiered rewards such as free shipping or gifts.
• Shipping protection: an opt-in shipping-protection add-on.

Shopper input

• Discount code: a field to apply a discount code.
• Notes: an order-notes field.

Content

• Banner: a message banner, with an optional countdown timer.
• Image: a single image or a hosted preset such as payment icons.
• Custom code: custom HTML or React anywhere in the cart.

Extending

• Custom templates: override how any block renders from its Code tab.

​

Blocks available in each section

Each section has a different set of blocks available. That keeps the layout focused and reduces clutter. Some of those blocks are state-specific (for example Empty cart only in the empty state). See How do carts work?.

​

Block validation errors

If a block’s settings contain an invalid value, a small red dot appears next to that block’s name in the sidebar. The dot stays until you fix the problem. It isn’t a dismissible notification. While any block has an error, saving is blocked. The Save button stays clickable, but selecting it shows an error toast (“Fix the errors in your cart blocks before saving”) and jumps to the first block with a problem, opening its settings so you can correct the highlighted field. Publish additionally requires no unsaved changes, so it stays unavailable until a clean save succeeds. Once the invalid field is corrected the dot disappears on its own, and saving proceeds normally.