Cart

When to useCopy Anchor Link

• The user is ready to check out, or asks to see or change their cart.
• They should confirm quantities and pick shipping before the store's checkout.

When not to useCopy Anchor Link

• The user is still choosing a product or its options. Use Product Options or Entity Cards.
• The user asks about one item's price or whether it is a good deal. Use Price Details.
• A sentence answers it ("how much is my cart?") and nothing needs changing.
• You don't have the cart from the store. Never invent items, prices, shipping or discounts.
• The order is already placed. Show a Result Receipt instead.

How the agent should use itCopy Anchor Link

• Pass items, prices, shipping and promo exactly as the store's cart returned them, in one currency.
• Only set promo for a discount the store has already applied.
• On checkout, update the store's cart to the returned items and shipping, then open the host's checkout. The host recomputes the total.
• Never collect payment, card or bank details in chat. Payment happens only in the host's checkout.
• On keep_shopping, leave the cart as it was and help the user find more.

Checkout is a handoffCopy Anchor Link

The Cart never takes payment and has no payment fields. Pressing checkout sends the final lines and shipping choice back, and your app opens its own checkout (a hosted payment page, your checkout route, a native sheet) where the real amount is calculated and charged. total in the result is the figure the user saw, for the agent's reply and your logs; never charge it.

Editing the cartCopy Anchor Link

• Quantities go from 1 to maxQuantity (default 10, or the current quantity if higher). Remove a line with its remove button; "Undo" brings it back.
• Shipping shows as one row with the chosen method, its arrival and its price. Change expands the other methods; picking one collapses the list again. With a single method there is nothing to change.
• Every line is always visible: the item list never scrolls inside the card.
• Removing the last line shows "Cart is empty" and disables checkout.
• Totals update as the user edits: subtotal, shipping, the discount (never more than the subtotal) and the total, all in integer minor units so 3 × 2.49 is exactly 7.47. Each change is announced to screen readers with the new total.

The math lives in cart-totals.ts as a pure computeTotals(items, shippingPrice, promoAmount) you can reuse on the server.

InstallationCopy Anchor Link

npx shadcn@latest add https://your-site.com/r/cart.json

UsageCopy Anchor Link

import { tool } from "ai"
import { cartTool } from "@/components/genui/cart.schema"

const tools = {
  // No execute: the user's decision is the tool result.
  [cartTool.name]: tool({
    description: cartTool.description,
    inputSchema: cartTool.inputSchema,
  }),
}

Render the tool call, return the user's decision as the tool result, and open your own checkout:

import { Cart } from "@/components/genui/cart"

function ToolPart({ part, addToolResult }) {
  if (part.type !== "tool-review_cart") return null

  return (
    <Cart
      {...part.input}
      status={part.state === "input-streaming" ? "streaming" : undefined}
      result={part.state === "output-available" ? part.output : undefined}
      onResult={async (result) => {
        addToolResult({
          tool: "review_cart",
          toolCallId: part.toolCallId,
          output: result,
        })
        if (result.action === "checkout") {
          // Your store's cart and checkout recompute prices and take payment.
          await updateCart(result.items, result.shippingId)
          router.push("/checkout")
        }
      }}
    />
  )
}

The agent receives one of:

{ action: "checkout", items: [{ id: "sku_4471-black-42", quantity: 1 }, { id: "sku_8810-m", quantity: 2 }], shippingId: "standard", total: 165 }
{ action: "keep_shopping" }

Lines the user removed are left out of items.

With LangGraphCopy Anchor Link

Push it from a graph node with ui.push({ name: "review_cart", props: { toolCallId, ...args } }, { message }), and render the thread's UI messages with the Renderer.

Restoring from historyCopy Anchor Link

When a conversation is reloaded, pass the stored result back as result. After a checkout it shows a compact read-only summary and "Sent to checkout"; after keep shopping it shows the cart locked. It never calls onResult again, so the cart can't be sent twice. With the AI SDK, that's the tool call's output:

<Cart
  {...part.input}
  result={part.state === "output-available" ? part.output : undefined}
/>

SchemaCopy Anchor Link

CartItem

ShippingOption

Host props: status (streaming, ready, checked_out, kept_shopping), onResult, result and className.

SourceCopy Anchor Link