Skip to main content
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

ParameterTypeRequiredDescription
requeststringYesThe 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_idstringNoThe 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_orderbooleanNoStart 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

{ "name": "buy", "arguments": { "request": "order a caesar salad from Zuni on DoorDash" } }