> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aftersell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How do blocks work?

> Understand Aftersell Cart blocks: sections and sub-blocks, filled vs empty, limits, locked blocks, conditions, and per-block settings.

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?](/aftersell/cart/how-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**](/aftersell/cart/cart-items-block) hosts sub-blocks: the **Product** row (the line-item row itself), [**Subscription upgrade**](/aftersell/cart/subscription-upgrade-block), and [**Custom code**](/aftersell/cart/custom-code-blocks).

## 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

<Info>
  The **empty cart state** is the whole empty layout. The **Empty cart block** is one block inside it. See [How do carts work?](/aftersell/cart/how-carts-work) for the difference.
</Info>

## 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:

| Block          | Maximum per cart state |
| -------------- | ---------------------- |
| Banner         | 3                      |
| Image          | 3                      |
| Product add-on | 3                      |
| Summary        | 2                      |
| Custom code    | Unlimited              |

## 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**](/aftersell/cart/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**](/aftersell/cart/custom-templates). 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.

|                  | **Eye toggle**                                | **Conditions**                                          |
| ---------------- | --------------------------------------------- | ------------------------------------------------------- |
| **What it does** | Hide or show the whole block for all shoppers | Pick which settings variant a shopper sees (or nothing) |
| **Based on**     | Your choice in the editor                     | Shopify market, customer country, or customer currency  |
| **Where**        | Sidebar eye icon on most blocks               | Settings panel for blocks that support conditions       |

**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](/aftersell/cart/rewards-block) tier thresholds for spend/quantity progress, or the [Cart SDK](/aftersell/cart/sdk-overview) 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**](/aftersell/cart/rewards-block#per-market-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](/aftersell/cart/header-block): title, item count, logo, and close control, pinned to the top.
* [Cart items](/aftersell/cart/cart-items-block): the items customers add to cart; repeats per line.
* [Subscription upgrade](/aftersell/cart/subscription-upgrade-block): sub-block that offers to convert a line to a subscription.
* [Summary](/aftersell/cart/summary-block): totals, savings, and applied discounts.
* [Checkout button](/aftersell/cart/checkout-button-block): the primary call-to-action to checkout.
* [Empty cart](/aftersell/cart/empty-cart-block): the content shown when the cart is empty.
* [Express payments](/aftersell/cart/express-payments-block): accelerated checkout buttons (Shop Pay, PayPal, and so on) inside the cart.

**Merchandising**

* [Upsells](/aftersell/cart/upsells-block): strategy-picked product recommendations.
* [Product add-on](/aftersell/cart/product-add-on-block): a single specific product offered as an add-on.
* [Rewards](/aftersell/cart/rewards-block): tiered rewards such as free shipping or gifts.
* [Shipping protection](/aftersell/cart/shipping-protection-block): an opt-in shipping-protection add-on.

**Shopper input**

* [Discount code](/aftersell/cart/discount-code-block): a field to apply a discount code.
* [Notes](/aftersell/cart/notes-block): an order-notes field.

**Content**

* [Banner](/aftersell/cart/banner-block): a message banner, with an optional countdown timer.
* [Image](/aftersell/cart/image-block): a single image or a hosted preset such as payment icons.
* [Custom code](/aftersell/cart/custom-code-blocks): custom HTML or React anywhere in the cart.

**Extending**

* [Custom templates](/aftersell/cart/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.

| Section    | Blocks available                                                                                                                                    |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Header** | Header, Banner, Rewards, Image, Custom code                                                                                                         |
| **Body**   | Banner, Notes, Discount code, Cart items, Empty cart, Custom code, Rewards, Product add-on, Shipping protection, Image, Upsells                     |
| **Footer** | Banner, Notes, Discount code, Custom code, Rewards, Product add-on, Shipping protection, Express payments, Image, Upsells, Summary, Checkout button |

Some of those blocks are state-specific (for example Empty cart only in the empty state). See [How do carts work?](/aftersell/cart/how-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.

<Note>
  Hidden blocks are still validated. A block you've hidden can hold an invalid setting, show an error dot, and block saving exactly like a visible one, so if saving is blocked and every visible block looks fine, check your hidden blocks.
</Note>