> Documentation index: https://www.xekta.com/llms.txt

# cart_build

> Turn a shopping list in plain words into a cart at one shop.

The fastest way from a list ("milk, eggs, a loaf of bread") to a cart. One cart holds one shop.

| | |
| - | - |
| Type | Write: changes a cart or an order |
| Needs a cart the buyer approved | No |
| Moves money | No |

**Tool description (what the assistant sees)**

```text
Matches natural-language item requests against live shop catalogs and writes a cart for a single shop (one cart holds one shop). Returns the cart_id. When two or more shops carry items from the list and no shop is chosen yet (no shop_id, no open cart), no cart is written: the result has mode "shops" and next_step "buyer_chooses_shop", each shop with items_found of items_total, its missing items and total, the shops with the whole list first. The same request with the chosen shop's shop_id builds the cart at that shop.
```

## Parameters

| Name | Type | Required | Description |
| - | - | - | - |
| `items` | `string[]` | Yes | The list, one entry per item in the buyer's own words. 1 to 50 entries. |
| `near` | `object` | No | Where the buyer is right now, in the same form as `product_search`'s `near`. Nearby shops are preferred, and the cart remembers it for the distance shown at approval. |
| `shop_id` | `uuid` | No | Build the cart at this shop. Set it after the buyer picked one from the shops list. |
| `preferences.max_total` | `number` | No | Keep the cart at or under this total. |
| `preferences.prefer_organic` | `boolean` | No | Prefer organic matches. |
| `preferences.preferred_retailers` | `string[]` | No | Prefer these shops, by name. |
| `preferences.avoid_attributes` | `string[]` | No | Avoid items with these attributes. |

## Notes

- When the result is `mode: "shops"`, no cart exists yet. Show how many of the items each shop has and what is missing, let the buyer choose, then call again with `shop_id`.
- Shops that have the whole list come first. When no shop has everything, say so plainly.

## What to call next

[`cart_get`](https://www.xekta.com/docs/tools/cart-get.md) to read the real total back, then [`cart_approve`](https://www.xekta.com/docs/tools/cart-approve.md).