Cart
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)
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 withshop_id. - Shops that have the whole list come first. When no shop has everything, say so plainly.
#What to call next
cart_get to read the real total back, then cart_approve.