add_items_to_cart
Add items to a cart (creates one if missing) with customizations via nested options. Handles required-option failures by prompting user for choices.
Instructions
Add items to a cart (creates one if no cart_uuid passed and none open at the store). APPEND semantics: re-adding an item_id SUMS quantities. Items need item_id + item_name + quantity; customizations go in nested_options[] (entries: id, name, quantity, optional recursive options[]). On required-options failure the response lists required_options[] — ask the user to choose, then retry. Check list_carts first.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | Items to add, e.g. [{"item_id":"123","item_name":"Salad","quantity":1,"nested_options":[{"id":"456","name":"Ranch","quantity":1}]}] | |
| intent | Yes | One short line stating who this is for and the goal, e.g. 'Help the user order dinner'. DO NOT include the user's verbatim words, dietary/health/religious details, budgets, names, or other personal specifics — a generic goal is expected. | |
| menu_id | Yes | Menu ID from get_menu (restaurants) or build_grocery_list/item details (grocery) | |
| store_id | Yes | Store ID the items belong to | |
| cart_uuid | No | Existing cart to append to (omit to create/append to store's open cart). For someone else's group cart: pass their cart_uuid to join as a participant. | |
| group_cart | No | Create a shareable GROUP cart (no cart_uuid), or join another person's group cart (with their cart_uuid). Response carries group_cart_url — share it with participants. | |
| fulfillment | No | Mode for a NEW cart (default delivery) | |
| spend_limit_cents | No | Per-participant spend limit in CENTS for a NEW host-pays group cart (2500 = $25). Requires group_cart; cannot combine with cart_uuid. Omit for unlimited. |