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

# Approval

> Only the buyer can approve an order. How the assistant asks, where the buyer answers, and what each answer means.

> [!WARNING]
> An assistant cannot approve. "Yes", "ok" or "just buy it" typed in the chat is not approval, and there is no field that lets an assistant tell the server otherwise.

## How it works

1. **Show the cart.** [`cart_get`](https://www.xekta.com/docs/tools/cart-get.md) returns `buyer_summary`: every item with quantity and unit price, the amount due, and which shop the buyer collects from. Send that text as it is and ask.
2. **Ask.** Call [`cart_approve`](https://www.xekta.com/docs/tools/cart-approve.md) with the `cart_id` and the cart's `total_cents`. This asks the buyer; it does not approve.
3. **The buyer answers.** A confirmation box with the cart and Approve / No appears in front of them. The text comes from XEKTA's own record of the cart, not from the assistant. Their answer travels back outside the conversation.
4. **Read the status,** then act on it.

## Where the buyer answers

| Place | When |
| - | - |
| An approval box XEKTA draws inside the chat | On clients that can render it. |
| A confirmation box the client shows | On other clients that can ask the user. |
| A XEKTA approval page, signed in as themselves | When no box can be shown, and **always** for totals over $200. |
| A 4-digit code texted to the buyer's phone | On assistants such as Meta Muse and on device-link connections. Over $200, or over $300 in 24 hours, the approval page is used instead. |

## The statuses

| `status` | Meaning | What the assistant does |
| - | - | - |
| `approved` | The buyer said yes. | Call [`checkout_create`](https://www.xekta.com/docs/tools/checkout-create.md). Do not ask again. |
| `refused` | The buyer said no. | Stop. Do not call `cart_approve` again for this cart unless the buyer asks. |
| `approval_box_open` | XEKTA's box is open in this chat. | Send no link. Tell the buyer to use the box and wait. If they say they see no box, call `cart_approve` again with `fallback: "link"`. |
| `approval_requested` | No box could be shown, or nobody answered in time. | Send the buyer the `approval_url` and wait for them to confirm on it. |
| `confirm_in_assistant` | A 4-digit code was texted to the buyer's phone. `code_sent_to` holds its last four digits. | Send no link. The buyer gives you the code; call `cart_confirm` with it as `confirm_code` and the `confirmation` exactly as given. |

## Rules

- **Any change to the cart drops the approval.** Add an item, or let a price move, and you have to ask again.
- **`checkout_create` refuses any cart nobody confirmed.**
- **Opening the `approval_url` yourself does nothing.** It needs a sign-in the assistant cannot produce, which is why the link does not have to be secret.
- **Never say the order is placed** before `checkout_create` has returned one. Say the true sentence for what happened: "I sent you the link; it is not bought until you confirm."
- **Never install anything** to obtain an approval, and never offer to simulate a purchase.

## Two tools the assistant does not call by itself

| Tool | Who calls it |
| - | - |
| `cart_approve_confirm` | The confirmation box itself, when the buyer answers. An assistant never calls it. |
| `cart_confirm` | Only on assistants such as Meta Muse and on device-link connections, with the 4-digit code the buyer received by text. |