cart_add
ChatGPTAdds one shop offer to an open cart. One cart holds one shop; restricted categories and quantities above available stock are refused. Restaurant items with required options need modifiers, and the error lists the available choices. Nothing is reserved or charged.
cart_approve
ChatGPTRequests the buyer's approval for a cart at its current total; the approval itself can only come from the buyer. Depending on the client, the buyer answers in a confirmation box the client shows, in an approval box XEKTA draws inside the chat, or on a secure XEKTA web page with their own sign-in (always used for totals over $200). Returns status approved, refused, approval_requested (with approval_url) or approval_box_open. total_cents is checked against the cart's current total and a mismatch is rejected. fallback: "link" returns the web-page link instead of a box. Any later change to the cart clears the approval, and checkout is refused for a cart without one.
cart_approve_confirm
ChatGPTRecords the buyer's Approve or Not now press from the XEKTA approval box. Requires the one-time key held by that box, so it only works from the box itself.
cart_build
ChatGPTMatches natural-language item requests against live shop catalogs and writes a cart for a single shop (one cart holds one shop). Returns the cart_id.
cart_create
ChatGPTOpens a cart for one buyer and one shop. Idempotent: returns the existing open cart when one is already open for this pair. Nothing is reserved or charged.
cart_get
ChatGPTReturns one cart with its items, frozen prices and total. Read-only.
cart_set_quantity
ChatGPTLowers the quantity of one cart line or removes it (qty 0). For items sold by weight, weight_lb (or qty) sets the amount up or down, replacing the earlier amount. When the same item appears on several lines with different options, line_id selects one. Any change clears the buyer's approval of the cart. Nothing is reserved or charged.
checkout_create
ChatGPTPlaces the order for a cart the buyer has approved. Refuses any cart without the buyer's current approval; approval cannot be passed as a field. Enforces one shop per cart, holds the stock, and places an authorization hold on the card the buyer saved with XEKTA — XEKTA charges it automatically when the buyer picks the order up (the shop enters their pickup code) — the buyer pays nothing at the counter — and the hold is released if the order is cancelled. Pickup is the default fulfillment: the response carries the pickup_code, or — when pickup_code_withheld is true — the buyer finds it in their own XEKTA account at pickup_code_url. The buyer reads the code to the shop at the counter.
checkout_prepare
ChatGPTBuilds a checkout summary for a cart without placing an order or touching payment. The response carries requires_user_approval=true and purchase_executed=false.
feedback_submit
ChatGPTRecords free-text feedback about a XEKTA tool or a recent error. Every structured error is already recorded server-side; this adds commentary to it. With tool_name, XEKTA tries to link the feedback to the caller's most recent error from that tool within a short time window; the response's linked_to_error and linked_error (error_code, occurred_at) show which error was matched, if any.
price_compare
ChatGPTCompares prices for a query across active shops, cheapest first. Out-of-stock offers are left out unless nothing is in stock. Read-only.
product_search
ChatGPTSearches the catalogs of approved XEKTA shops (groceries and prepared food for pickup) by name, brand, category or attributes and returns ranked offers with price, stock state and shop details. Shops open now rank first; offers from shops outside their posted hours are included with shop_open_now: false and shop_opens_at, and an order to such a shop goes through only once it opens. With near (a city or neighborhood, a street address, a ZIP code or coordinates) nearby shops rank first and carry distance_miles; if no shop within the radius has a match, the nearest ones are returned instead. Without near the buyer's saved home address is used, or results come unsorted by distance — no location is needed to browse — and location_basis reports which location was used. A general query such as "markets", "grocery stores" or "restaurants" returns a few example items from each shop instead of matching item names. An order a shop does not answer within 10 minutes is cancelled automatically and nothing is charged. An offer with image_url has a photo: image_source "shop" is the shop's own photo, "stock" is a XEKTA stock photo of the dish that is only to be displayed together with its image_note label. Read-only.
substitution_suggest
ChatGPTSuggests alternatives for an unavailable SKU or a free-text query from the same live shop catalogs product search reads. Optional filters: merchant_id, in_stock_only, max_unit_price_cents and limit (max 5). Returns suggestions only; nothing is added to a cart, and the buyer's substitution policy decides what may be substituted. Read-only.
user.delivery.confirm
ChatGPTConfirms the buyer received the items of a collected order. Closes the order's dispute window, after which the shop's payout is no longer held. XEKTA already charged the buyer's card automatically at pickup; nothing new is charged.
user.delivery.contest
ChatGPTOpens a dispute on a collected order (for example wrong or missing items). Marks the order disputed and keeps the shop's payout held while the dispute is open.
user.order.cancel
ChatGPTCancels the buyer's own order, releases the card hold and any held stock, and notifies the shop. Free while the shop has not started preparing it. Refused once someone at the shop marks it as being prepared or ready (an uncollected order is then charged in full and paid to the shop), and once it is delivered, cancelled, disputed or charged. An order XEKTA's own timer moved to ready without the shop touching it can still be cancelled. There is no time limit.
user.order.confirm_partial
ChatGPTRecords the buyer's decision when a shop could fill only part of an order: keep the reduced order, swap a missing item for one of the substitutes the shop offered, or cancel. Nothing is handed over or charged while the decision is pending.
user.orders.status
ChatGPTReports what changed in the buyer's orders since the last check and the current state of every open order: status, shop name and phone, pickup address, deadlines and estimated_ready_at (the shop's ready time for that order, or null). Each entry in updates is a ready-to-send sentence and is returned once. pending_decisions lists orders waiting for the buyer's decision on missing items and stays populated until they decide. poll_interval_seconds, open_orders and keep_polling describe whether any order is still open; an order can stay open up to 48 hours. Status "accepted" means the order was sent to the shop and nobody there has started it; it is not an approval by the shop. The shop's first action moves it to "preparing". Each order's status_text is a ready-to-send sentence.
user.payment_method.setup
ChatGPTStarts saving a card for the buyer. Returns a Stripe setup client secret for the buyer's own payment page, plus the cards already on file; card numbers are never accepted as tool input. With replace: true it returns a link that saves a new card and removes the old one once the new one is saved. Safe to call repeatedly.
user_pickup_confirm
ChatGPTRecords the buyer's own word about an order that is ready for pickup. Without picked_up it is the buyer's presence at the counter: a signal the shop cannot produce on its own, kept as evidence if the handover is later disputed; the pickup code alone completes the handover. With picked_up: true the buyer confirms collecting the order and it is charged now, the same as when the shop enters the pickup code — this covers a buyer who left without giving the code. With picked_up: false the buyer says they did not collect an order the shop marked as handed over without the code; nothing is charged and XEKTA support reviews it. Does not close the dispute window. Repeating a call is harmless.