# Cart Profile Tools

> Inspect, assign, and edit cart profiles through the Storefront MCP.

Canonical URL: https://fa7e86e3d553:3005/tools/cart

> **MCP v3 routing:** The operation names on this page are retained as action-contract references. Do not call them as top-level tools. Pass the former name to `lexsis_discover`, then call the returned router and action with the documented parameters inside `args`.

The Storefront MCP provides three cart tools. Profile lifecycle management,
publishing, defaults, campaign targeting, and history remain in the Lexsis app.

Call `get_cart_profile` before assigning or editing a cart.

Open <AppLink to="cart">Storefront → Cart</AppLink> for profile creation,
visual previews, publishing, rollback, defaults, assignments, and history.

## get_cart_profile

Inspect a profile draft or resolve the effective cart for a page.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `page_id` | UUID | No | Resolve the cart a shopper receives on this page |
| `cart_profile_id` | UUID | No | Fetch one editable profile |
| `store_id` | UUID | No | Optional store hint for a multi-store account |
| `include_available_profiles` | boolean | No | Include a compact profile list, defaults to `true` |

Pass either `page_id` or `cart_profile_id`, not both. Passing only `store_id`
lists the available profiles.

### Resolve a page

```json
{
  "name": "get_cart_profile",
  "arguments": {
    "page_id": "7f58258d-cb47-433c-9e35-672cafdffde2"
  }
}
```

The response includes `effective_profile.resolution_source`:

- `page`
- `campaign`
- `default`
- `legacy`
- `none`

The effective profile is the published snapshot used by the renderer. An
individually fetched profile is the editable draft and includes
`has_unpublished_changes`.

## set_cart_profile

Assign a published profile to one page. A new assignment replaces the previous
page assignment.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `page_id` | UUID | Yes | Target page |
| `cart_profile_id` | UUID or `null` | Yes | Published profile, or `null` to remove the page assignment |

```json
{
  "name": "set_cart_profile",
  "arguments": {
    "page_id": "7f58258d-cb47-433c-9e35-672cafdffde2",
    "cart_profile_id": "6b36d37e-065d-409e-b15a-66dd76934a31"
  }
}
```

To restore campaign, store-default, or legacy fallback resolution:

```json
{
  "name": "set_cart_profile",
  "arguments": {
    "page_id": "7f58258d-cb47-433c-9e35-672cafdffde2",
    "cart_profile_id": null
  }
}
```

The tool returns the effective profile after the assignment change. Lexsis
then refreshes the affected published Shopify page automatically.

## edit_cart

Apply a partial update to a profile draft. The tool never publishes.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `cart_profile_id` | UUID | Yes | Profile to edit |
| `store_id` | UUID | No | Optional store hint |
| `patch` | object | Yes | Partial cart configuration |
| `change_note` | string | No | Short reason for the draft change |
| `expected_version` | positive integer | Yes | Profile version returned by `get_cart_profile` |

The patch accepts:

| Field | Purpose |
|---|---|
| `cart_mode` | Drawer, sheet, modal, fullscreen, or page presentation |
| `layout_schema` | Ordered modules and enabled state |
| `cart_rules` | Conditional cart behavior |
| `commerce_config` | Offers, shipping, purchase options, checkout, currency, and design settings |
| `custom_css` | Sanitized, profile-scoped CSS; use `null` to remove |
| `design_patch` | Typed `CartDesignSpecV1` JSON Merge Patch |

Nested `commerce_config` objects are merged into the existing draft. Arrays
such as `offer_slots` and `upsells` replace the existing array.

`design_patch` merges recursively into the existing `design_spec`. Passing
`null` for an optional design field removes that override so the selected
preset or parent value applies again.

### Apply a visual preset and responsive overrides

```json
{
  "name": "edit_cart",
  "arguments": {
    "cart_profile_id": "6b36d37e-065d-409e-b15a-66dd76934a31",
    "expected_version": 8,
    "change_note": "Use the softer campaign cart treatment",
    "patch": {
      "design_patch": {
        "schema_version": 1,
        "preset_id": "soft-beauty",
        "tokens": {
          "colors": {
            "accent": "#8F4A5B",
            "surface_alt": "#FBF7F5"
          },
          "spacing": {
            "density": "spacious"
          }
        },
        "modules": {
          "cart_lines": {
            "variant": "editorial",
            "image_aspect": "portrait",
            "free_gift": {
              "variant": "gift_card",
              "badge_text": "A gift for you",
              "lock_quantity": true
            }
          }
        },
        "responsive": {
          "mobile": {
            "tokens": {
              "spacing": {
                "density": "comfortable"
              }
            },
            "shell": {
              "width": "standard"
            }
          }
        }
      }
    }
  }
}
```

Supported presets are `clean-default`, `soft-beauty`, and
`compact-utility`. Design patches can control colors, typography, shape,
spacing, shell layout, cart lines, rewards, shipping, coupons, offers, order
summary, checkout, payment options, and the empty state.

### Update design and free shipping

```json
{
  "name": "edit_cart",
  "arguments": {
    "cart_profile_id": "6b36d37e-065d-409e-b15a-66dd76934a31",
    "expected_version": 8,
    "change_note": "Use the campaign cart treatment",
    "patch": {
      "cart_mode": "drawer-right",
      "commerce_config": {
        "free_shipping_threshold": 7500,
        "free_shipping_celebration": true,
        "cart_style": {
          "width": "440px",
          "responsive": {
            "mobile": "bottom-sheet"
          },
          "line_spacing": "comfortable"
        }
      }
    }
  }
}
```

Money thresholds use the store currency and are expressed in minor units. For
example, `7500` is 75.00 for a two-decimal currency.

### Configure an offer

```json
{
  "name": "edit_cart",
  "arguments": {
    "cart_profile_id": "6b36d37e-065d-409e-b15a-66dd76934a31",
    "expected_version": 8,
    "patch": {
      "commerce_config": {
        "offer_slots": [
          {
            "id": "pairs-well",
            "placement": "after_line",
            "source": "shopify_recommendations",
            "recommendation_intent": "COMPLEMENTARY",
            "heading": "Pairs well with",
            "trigger_product_ids": [],
            "recommend_product_ids": [],
            "max_items": 1,
            "enabled": true
          }
        ]
      }
    }
  }
}
```

### Add scoped CSS

```json
{
  "name": "edit_cart",
  "arguments": {
    "cart_profile_id": "6b36d37e-065d-409e-b15a-66dd76934a31",
    "expected_version": 8,
    "patch": {
      "custom_css": "[data-part=\"panel\"] { border-radius: 0; }\n[data-part=\"checkout\"] { font-weight: 600; }"
    }
  }
}
```

The CSS is scoped to the profile's cart root. It cannot alter the rest of the
page. External imports, external URLs, script escapes, and unbalanced rules are
rejected.

## Publishing

`edit_cart` changes only the draft. The response reports
`publish_required: true` when the live profile is unchanged. Review the preview
and publish from <AppLink to="cart">Storefront → Cart</AppLink>.

The response also returns the current `design_compiler_version`. If
`expected_version` is stale, reload the profile and reapply the intended patch
to the latest draft rather than overwriting another edit.

Publishing or rolling back a profile automatically refreshes affected
published Shopify pages. Page republishing is not a separate MCP operation.

This boundary prevents an agent edit from changing a shopper-facing cart
without merchant review.

## Related

- [Cart Profiles](/guides/cart-v2)
- [Page Management](/tools/page-management)
- [Cart Islands](/islands/cart)