Fahad AI
Docs / Cart and checkout

Cart and checkout

When a shopper adds something to the cart, the confirmation has to be true. The assistant adds, inspects and clears cart items through verified cart actions, then hands off to your normal WooCommerce checkout. It never narrates a success a tool did not return.

Add to cart from a product card

Every product card the assistant renders carries an Add to cart button. Clicking it does not ask the model to add anything. It posts straight to a verified cart endpoint, so there is no agent round-trip, the action is instant, and the confirmation you read reflects the real cart result rather than a sentence the model composed.

The request the card sends is small and explicit:

POST  (your store cart endpoint)
X-WP-Nonce: (session nonce)
Content-Type: application/json

{ "action": "add", "product_id": 128, "quantity": 1, "variation_id": 0 }

The endpoint validates the product, applies WooCommerce's own stock rules, and replies with the verified cart state. On success the reply carries the cart total, a View Cart link and a Checkout link, which the assistant surfaces as the two links below its confirmation. If the add fails, you get the real reason (product not found, option unavailable, out of stock) and no success line.

The endpoint is gated by the same nonce and rate limit as the chat itself, and it returns plain JSON rather than a stream, so WooCommerce sets its session cookie normally and a guest cart persists across the visit.

Variable products: pick an option first

For a variable product, there is no single thing to add until the shopper chooses. The card shows a Choose an option select listing the real variations. In-stock options are selectable, sold-out ones are shown but disabled, so the choices stay transparent without ever offering something that cannot be added.

The Add to cart button waits for a real selection. If no variation is chosen, the click moves focus to the select instead of adding anything. Once an option is picked, its variation_id goes to the endpoint, and the variation, not the parent product, is the source of truth for both price and stock. A sold-out size or colour is rejected even when the parent product still reports as in stock.

Viewing and removing cart items

Ask the assistant what is in the cart and it calls view_cart, which returns the current line items, each item's quantity and line total, the running totals, and the checkout URL. Each item comes back with a cart_item_key.

To take something out, the assistant calls remove_from_cart with that exact key:

remove_from_cart  { "cart_item_key": "a1b2c3d4e5f6..." }

WooCommerce removes the line and returns the new cart total. If the key does not match anything in the cart, the tool says so plainly rather than reporting a removal that did not happen.

Handing off to checkout

The assistant does not run payment or capture card details. A successful add ends with two links built from your store's own URLs:

From there the shopper completes the order through your normal checkout, with whatever gateways, taxes and shipping you already have configured. The assistant's job is to get the right items into a real cart and then step out of the way.

Why the confirmation can be trusted

The whole flow is built so a cart change is never described unless it actually happened. The card add reuses the same cart tools and the same validation the assistant would use, and reports back the verified state. The system prompt holds the model to the same line everywhere: only report success when a tool returns success, and never invent cart, order, or stock data.