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

# buy

> Shop and check out at linked merchants using natural language

Shop and check out, in natural language, across the merchants the user has linked. Pass the whole ask as `request` (for example, "order a caesar salad from Zuni on DoorDash") and the tool runs the shopping flow for you. It is conversational: it returns a `conversation_id`, and you call `buy` again with that same id to answer its questions or continue the order. Checkout, which charges a one-time card, happens only after the user explicitly confirms in a later message.

## Parameters

| Parameter         | Type    | Required | Description                                                                                                                                                    |
| ----------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `request`         | string  | Yes      | The natural-language ask or follow-up, e.g. "order a caesar salad from Zuni on DoorDash", "deliver to 123 Main St", or "yes, place the order".                 |
| `conversation_id` | string  | No       | The `conversation_id` returned by a previous `buy` call. Pass it back to continue the same order (keeps the cart and confirmation). Omit to start a new order. |
| `new_order`       | boolean | No       | Start a fresh shopping conversation instead of continuing the current one. Ignores any `conversation_id`.                                                      |

## Returns

The assistant's conversational turn as `message`: it may ask for the delivery address, show the cart and total to confirm, or report a placed order. A successful turn includes a `conversation_id` to pass back on your next call, and a `messages` array with the same turn split into ordered bubbles for multi-message surfaces. On failure, `status` is `conversation_start_failed` or `request_failed`; if the conversation is gone or closed, the error suggests retrying with `new_order: true`.

## Example

```json theme={null}
{ "name": "buy", "arguments": { "request": "order a caesar salad from Zuni on DoorDash" } }
```