Guides

Approval

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

View as Markdown

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

Show the cart. cart_get 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.
Ask. Call cart_approve with the cart_id and the cart's total_cents. This asks the buyer; it does not approve.
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.
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`. 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.