Invoice

When to useCopy Anchor Link

• The user asks about a specific invoice, bill or receipt the agent found in their email, accounting tool or bank: whether it was paid, what they owe, when it's due, or where the receipt is.
• They need the line items, totals or payment details of that one document, or to act on it (pay, download, add to expenses).

When not to useCopy Anchor Link

• The agent doesn't have the document from a tool result. Never invent amounts, dates or states.
• The user wants an overview of many documents. Use a Data Table.
• The agent just took an action (sent a reminder, paid a bill). Show a Result Receipt.
• The user is still shopping. Use a Cart.

How the agent should use itCopy Anchor Link

• Pass every amount, date, party and state exactly as the source returned them, in one currency. Don't round, recompute or fix totals: the component flags totals that don't add up.
• Set direction for invoices, so reminders go to the customer and payments go to the vendor.
• Only pass last4 for payment, never a full card or account number. The schema rejects anything but 4 digits.
• On pay, open the host's payment flow. Never collect payment details in chat, and never treat the document as paid until the source says so.
• On remind or forward, draft the message and confirm recipients before sending. On dispute, use the user's reason.

Three kinds of documentCopy Anchor Link

Pass actions to choose the buttons yourself, from the closed set pay, download, forward, dispute, add-to-expenses and remind. The first is the primary button and the second a text button; any more show as labelled icon buttons. Pay and remind are hidden when nothing is owed (paid, void, refunded, draft).

Totals that don't add upCopy Anchor Link

The component reconciles the document in integer minor units, within 0.01: line amounts against the subtotal, the subtotal less discounts plus taxes and shipping against the total, and amount paid plus amount due against the total. When a check fails it shows a short warning, such as "Totals don't add up: lines sum to $15.00, but the total is $16.00", instead of hiding it. The agent must not paper over it: pass the figures as printed and mention the discrepancy.

Taxes already inside VAT-inclusive prices take included: true; they show as "Includes VAT 18%" and aren't added again.

The helpers live in invoice-utils.ts (reconcile, amountOwed, relativeDue, defaultActions, …), pure functions you can reuse on the server.

LayoutCopy Anchor Link

The card leads with one figure: the amount due while something is owed, otherwise the total, with the due (or return-by) date under it. Line items, the totals breakdown and the payment method follow. The issuer (or, for invoices you sent, the recipient) is the one line under the title. A collapsed Details row holds the rest: both parties with their addresses, tax IDs and email, the issue date of bills and invoices, and the payment reference.

DatesCopy Anchor Link

Due and return dates get relative text: "Due Oct 13 · in 5 days", "Due Sep 19 · Overdue by 19 days", "Return by Oct 24 · 16 days left to return". It's computed after mount, so server and client render the same markup. Pass now to compare with a fixed moment instead (tests, demos, a server-rendered snapshot). Overdue text uses destructive color plus an icon, and the state badge carries its own label, so nothing relies on color alone. The "Due soon" badge is left out when the due line already says it.

ActionsCopy Anchor Link

• Pay is a handoff. The button reads "Pay $132.89" but never collects payment: it returns { action: "pay" } and your app opens its own payment flow (the biller's portal, your payments page, a native sheet).
• Dispute opens a text box for the reason, and returns { action: "dispute", reason }.
• After an action, its button locks and the footer confirms it quietly ("Sent to your payment flow", "Added to expenses"). The other actions stay available, and each calls onResult once.

InstallationCopy Anchor Link

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

UsageCopy Anchor Link

import { tool } from "ai"
import { invoiceTool } from "@/components/genui/invoice.schema"

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

Render the tool call and handle each action:

import { Invoice } from "@/components/genui/invoice"

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

  return (
    <Invoice
      {...part.input}
      status={part.state === "input-streaming" ? "streaming" : undefined}
      result={part.state === "output-available" ? part.output : undefined}
      onResult={(result) => {
        if (result.action === "pay") openPaymentFlow(part.input)
        if (result.action === "download") downloadDocument(part.input)
        if (part.state !== "output-available") {
          addToolResult({ tool: "show_invoice", toolCallId: part.toolCallId, output: result })
        } else {
          // Later actions: send them as a follow-up so the agent can act.
          sendMessage({ text: `Invoice action: ${JSON.stringify(result)}` })
        }
      }}
    />
  )
}

The agent receives one of:

{ action: "pay" }
{ action: "download" }
{ action: "forward" }
{ action: "add-to-expenses" }
{ action: "remind" }
{ action: "dispute", reason: "Charged twice for September" }

With LangGraphCopy Anchor Link

Push it from a graph node with ui.push({ name: "show_invoice", 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, or an array of results when several actions were taken. Those actions show as done and their buttons stay locked; they never call onResult again. With the AI SDK, that's the tool call's output:

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

SchemaCopy Anchor Link

Host props: status (streaming, ready, submitting, done), now, onResult, result and className.

SourceCopy Anchor Link