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

# The Cart

> A cart is the merchant's shopping bag. create_cart starts one, update_cart fills it.

![Cart lifecycle: empty cart, filled cart, cleared](https://mintcdn.com/agentmall/ZuoglRqW4CDsIaRs/images/cart.svg?fit=max\&auto=format\&n=ZuoglRqW4CDsIaRs\&q=85\&s=4d780889352d0d5d1d7cc173c305f332)

A cart is the merchant's shopping bag, managed through AgentMall's browser. `create_cart` starts one, `update_cart` fills it.

## Creating a cart

```json theme={null}
{ "shopper_id": "shp_demo", "merchant_id": "mrc_walmart", "account": "platform" }
```

`create_cart` returns an empty cart. The `id` in the response (prefixed `ses_`) is the session id used for every subsequent call.

## Updating the cart

`update_cart` replaces the entire cart. It clears the merchant cart first, then adds each line in order. An empty `line_items` array just clears.

```json theme={null}
{
  "id": "ses_...",
  "line_items": [
    { "item": { "id": "123456789", "url": "https://www.walmart.com/ip/123456789" }, "quantity": 2 },
    { "item": { "id": "987654321", "url": "https://www.walmart.com/ip/987654321" }, "quantity": 1 }
  ]
}
```

Each line needs:

| Field | Type | Required | Notes |
| - | - | - | - |
| `item.id` | string | Yes | Product id from search or variant id from `get_product` |
| `item.url` | string | Yes | Product page URL. Must already point to the chosen size/colour. |
| `quantity` | integer | Yes | 1 to 12. List each product once. |
| `options` | object | No | Size, colour, or pack. Example: `{ "Clothing Size": "M" }` |

A failed add stops the call. Each add has a 90-second server-side deadline.

## Reading the cart

`get_cart` reads the live merchant cart. Returns `line_items` with per-line and cart-level `totals` (subtotal and total, in minor units of `currency`).

```json theme={null}
{
  "id": "ses_...",
  "merchant_id": "mrc_walmart",
  "currency": "USD",
  "line_items": [
    {
      "id": "...",
      "item": {
        "id": "123456789",
        "title": "Energizer MAX AA, 24 Pack",
        "price": 1697,
        "url": "..."
      },
      "quantity": 2,
      "totals": { "subtotal": 3394, "total": 3394 }
    }
  ],
  "totals": { "subtotal": 3394, "total": 3394 }
}
```

A line the merchant marks as unavailable carries `available: false` and a zero price. Remove it before checkout.

## Cancelling

`cancel_cart` returns the cart as last stored and releases the browser. The session ends as `abandoned`.

## Browser lifecycle

Each cart keeps one browser across all cart and checkout calls. If the browser is released (timeout, infrastructure), the next call opens a new one. The response includes `browser_released: true`. The new browser may be signed out or have a different merchant cart. Call `get_cart` to check.

## Errors

| Code | Meaning |
| - | - |
| `quantity_above_max` | At most 12 per line. |
| `option_required` | A size, colour, or pack is unselected. The error lists valid combinations. |
| `product_not_found` | The URL is not a product page on this merchant. |
| `product_unavailable` | The merchant will not sell it. The line is not added. |
| `already_in_cart` | That product is listed twice. Put the quantity on one line. |
| `timeout` | The add took too long. Call `get_cart` to see whether the item landed, then retry if it did not. |
| `cart_clear_failed` | The clear stopped partway. The error has `removed` and `left`. Call again to keep clearing. |
| `merchant_blocked` | A block page appeared instead of the cart. Wait and retry. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.