# Cart Profiles

> Configure, publish, and target reusable cart profiles.

Canonical URL: https://fa7e86e3d553:3005/guides/cart-v2

Cart profiles are reusable, versioned cart experiences. A store can keep
multiple profiles for different merchandising strategies, publish stable
versions, choose a store default, and assign a profile to a page or campaign.

Open <AppLink to="cart">Storefront → Cart</AppLink> to create, preview,
publish, assign, and review cart profiles.

## Page and cart ownership

The page and cart are separate:

- Page sections own the storefront content.
- Cart V2 is enabled by default and cannot be disabled.
- A cart profile owns the drawer HTML, module order, rules, offers, behavior,
  responsive mode, and cart-only styling.
- The renderer resolves and injects the cart after the page sections.
- Page titles, SEO metadata, and page section HTML never select a cart profile.

Do not add `DrawerShell`, `CartLines`, or other cart islands to page source.
Publish validation rejects an inline cart.

## Resolution order

The renderer selects one published profile for every cart-profile page:

```text
page assignment > campaign assignment > store default > legacy fallback
```

A page assignment is the most specific. Removing it restores the next
available fallback instead of disabling the cart.

Only published, non-archived profiles can become defaults or assignments.
Editing a profile creates draft changes. The live cart remains on its current
published snapshot until the merchant publishes from
<AppLink to="cart">Storefront → Cart</AppLink>.

Changing an assignment, default, published profile version, archive state, or
rollback automatically refreshes the affected published Shopify pages after
the database change commits. You do not need to republish each page manually.

## Default cart behavior

New page source does not need a Cart V2 flag. Configure and target the cart
profile separately. The compiler continues accepting `use_cart_v2:true` on
older pages as a deprecated compatibility field. It rejects
`use_cart_v2:false` because Cart V2 cannot be disabled.

## How a cart opens

Cart triggers and cart presentation communicate through the shared
`cart:open` event:

1. The renderer injects the resolved profile's `DrawerShell` after the page
   sections.
2. `BuyBox`, `QuickAdd`, `StickyBar`, product cards, and offer cards add the
   selected variant through the shared cart action.
3. The purchase control shows its own loading state while the mutation runs.
4. After a successful mutation, the cart action emits `cart:open` with the
   confirmed variant and quantity in shared cart state.
5. The storefront hydrator bridges a DOM `cart:open` event to the shared cart
   event bus.
6. The injected `DrawerShell` listens for `cart:open`, opens, and hydrates its
   child cart islands on first use.
7. Mutation errors stay on the purchase control and do not present a false
   successful drawer state.

The site header cart button uses the same `cart:open` event. A custom
storefront control can open the cart with:

```js
document.dispatchEvent(new CustomEvent("cart:open"))
```

The trigger does not need to know which profile is assigned. Profile resolution
happens before hydration, so every valid trigger opens the cart already
selected for that page.

The header cart button and badge subscribe to the same cart state as the
drawer. A successful add must therefore be verified in two separate steps:
the Shopify/cart mutation succeeds, and the configured drawer becomes visibly
open with the correct variant, quantity, price, and image.

## Missing profile behavior

A commerce page with purchase controls but no effective profile is invalid.
Preview marks the page with `data-lx-cart-profile-state="missing"` and reports:

```text
This preview has purchase controls but no effective Cart V2 profile.
```

Fix the store default or page/campaign assignment before publishing. Do not
work around the warning by manually embedding DrawerShell or cart child
islands in page source.

## Profile configuration

A profile can configure:

- Desktop and mobile cart modes
- Drawer width and motion
- Visual presets, colors, typography, shape, spacing, and responsive overrides
- Line-item layout, media, quantity controls, removal controls, and sale prices
- Module order and enabled modules
- Free-shipping threshold and celebration
- Shopify selling-plan presentation
- Manual and Shopify-powered product offers
- Cumulative reward milestones, automatic gifts, coupons, and payment logos
- Conditional cart rules
- Checkout behavior
- Scoped custom CSS

The required layout modules are cart lines, order summary, and checkout.
Shipping progress, subscription presentation, payment methods, and product
offer modules can be enabled, disabled, and reordered.

## Cart design contract

Every profile has a `CartDesignSpecV1` document:

```json
{
  "schema_version": 1,
  "preset_id": "clean-default",
  "tokens": {},
  "shell": {},
  "modules": {},
  "responsive": {}
}
```

The three built-in presets are:

| Preset | Intended result |
|---|---|
| `clean-default` | Balanced default with standard spacing and controls |
| `soft-beauty` | Wider editorial layout, softer surfaces, larger media, and brand typography |
| `compact-utility` | Narrow, dense cart with compact line items and controls |

The compiler resolves the selected preset first, then applies explicit
overrides. The saved draft keeps the authored specification while preview and
production use the deterministic compiled result.

### Design tokens

`tokens` controls:

- Colors: background, surfaces, text, accent, border, success, warning, error,
  reward, and coupon
- Typography: brand/body/heading family, title and body scale, and weight
- Shape: radius, control radius, border width, and shadow
- Spacing: density and section gap

### Shell and module design

`shell` controls width, header layout, title, item-count treatment,
close-button style, sticky header/footer, and content background.

`modules` can separately style reward progress, free shipping, cart lines,
coupon summary, product offers, order summary, checkout, payment options, and
the empty state. Cart-line design also controls media shape and size, dividers,
quantity and removal controls, sale-price treatment, and free-gift appearance.

### Responsive overrides

Use `responsive.mobile`, `responsive.tablet`, and `responsive.desktop` to
override tokens, shell settings, or module design at a specific viewport.
Responsive values merge over the selected preset and base profile design.

## Preview states

The Cart editor can preview real layout states without publishing:

- One-time purchase
- Subscription purchase
- Shipping reward unlocked
- Empty cart
- Error state

Preview uses the same compiled design contract and cart runtime as published
pages. Verify each applicable state on mobile and desktop before publishing.

## Cart module catalog

These are renderer-managed building blocks selected by the effective profile:

| Island | Responsibility |
|---|---|
| `DrawerShell` | Responsive drawer, sheet, modal, fullscreen, or dropdown container |
| `CartLines` | Product image, variant, quantity, removal, selling plans, and reward-line state |
| `CartSummary` | Subtotal and optional discounts, shipping, and tax rows |
| `CartCheckoutButton` | Checkout CTA, secondary CTA, item count, and payment providers |
| `CartProgressBar` | Simple free-shipping or tier progress |
| `CartRewardProgress` | Cumulative gifts, fixed-price products, discounts, and shipping rewards |
| `CartCoupons` | Curated offers, applied savings, coupon drawer, and manual code entry |
| `CartDiscountInput` | Direct discount-code application |
| `CartCrossSell` | Reactive profile-configured recommendations |

These island references document profile capabilities and styling contracts.
They are not instructions to add cart markup to storefront page source.

## Offers and subscriptions

Offer slots support these placements:

- `header`
- `after_line`
- `after_lines`
- `before_checkout`

An offer can use manually selected Shopify products or Shopify `RELATED` and
`COMPLEMENTARY` recommendations. Product IDs must be Shopify product GIDs.

Subscribe and Save is a line-item capability. It appears only when the product
or variant has real Shopify selling plans. Profiles can control whether the
purchase options are shown and whether they use cards or a select menu, but a
profile cannot create selling-plan eligibility.

## Profile styling

Page `theme_css` supplies the brand defaults used by the whole page. Profile
design settings and `custom_css` apply only to the cart.

Custom CSS is:

- Stored with the profile draft
- Sanitized before saving
- Scoped under the resolved cart profile root
- Shared by preview and production rendering
- Published only when the merchant publishes the draft

External CSS imports, external `url()` values, script escapes, and unbalanced
rules are rejected.

Example:

```css
[data-part="panel"] {
  border-radius: 0;
}

[data-part="checkout"] {
  font-weight: 600;
}
```

## MCP workflow

The MCP intentionally exposes only three cart operations:

1. `get_cart_profile` inspects a profile or resolves the effective profile for
   a page.
2. `set_cart_profile` assigns a published profile to a page or removes the page
   assignment.
3. `edit_cart` updates a profile draft, including offers, behavior, design, and
   scoped CSS.

Profile creation, duplication, publishing, rollback, defaults, campaign
targeting, history, and archival remain in the Lexsis app.

See [Cart Profile Tools](/tools/cart) for complete request examples.

## Migrating a legacy page

1. Remove `CartDrawer` and any inline `DrawerShell` from page sections.
2. Remove the obsolete `use_cart_v2` field from newly authored source.
3. Publish or select a cart profile in the Lexsis app.
4. Assign it to the page, or rely on the store default.
5. Verify add-to-cart and header cart controls both open the resolved profile.
6. Publish profile changes after previewing the draft.

## Related

- [Cart Profile Tools](/tools/cart)
- <AppLink to="cart">Open Cart profiles in the Lexsis app</AppLink>
- [DrawerShell](/islands/cart/drawer-shell)
- [Cart Lines](/islands/cart/cart-lines)
- [Quick Add](/islands/commerce/quick-add)
- [Sticky Bar](/islands/commerce/sticky-bar)