---
name: ttyinv-invoice
description: Create, validate, or render portable ttyinv invoices through ttyinv's authenticated REST API or MCP server. Use when an agent needs ttyinv/v1 Markdown, validation diagnostics, HTML, PDF, or PNG output; do not use for local-only processing where invoice data must not cross the network.
---

# ttyinv invoice

Use `TTYINV_AGENT_TOKEN` for authentication and `${TTYINV_BASE_URL:-https://app.ttyinv.com}` as the service URL. Never paste, print, log, commit, or place the token in a URL or file. Do not enable shell tracing or verbose HTTP output. Stop with setup guidance if the variable is absent. Every agent call requires this token.

Invoice requests are processed transiently and are not stored, but their contents cross the network. Before sending non-fabricated personal, financial, or business data, explain that boundary and obtain the authorization required by the active environment. Prefer the local ttyinv CLI when data must remain local.
Hosted HTML, PDF, and PNG rendering also requires an active lifetime purchase for the account that owns the token. Creating and validating invoices remain free.

## Choose a transport

- This skill assumes no harness, no skill directory, and no configuration format.
- Prefer the ttyinv MCP tools when your harness exposes them.
- The tool names are `create_invoice`, `validate_invoice`, and `render_invoice`.
- Some harnesses add a server prefix to each tool name. Match the ttyinv tool by its suffix.
- Use REST when your harness exposes no ttyinv MCP tools.
- Send `Authorization: Bearer $TTYINV_AGENT_TOKEN`, `Content-Type: application/json`, and `Accept: application/json`.
- Fetch `GET /api/v1` for the public discovery document.
- That document names each operation, tool, status meaning, and purchase rule.
- Fetch `GET /api/v1/invoices/schema` before you compose input.
- Its `ttyinv-agent/v1` envelope provides `operations.create`, `operations.validate`, and `operations.render`.
- Each operation states the exact `input` schema and the successful `output` schema.
- The service generates both schemas from the live REST and MCP contract.
- Use these schemas instead of an inferred or duplicated field list.

## Workflow

1. **Create** — build strict JSON from `operations.create.input` and call `create_invoice` or `POST /api/v1/invoices`. Keep the returned `source` as the portable invoice artifact.
2. **Validate** — send `{ "source": "..." }` to `validate_invoice` or `POST /api/v1/invoices/validate`. Do not claim success unless `valid` is true; report returned diagnostics without exposing unrelated payload content.
3. **Render when requested** — only after successful validation, call `render_invoice` or `POST /api/v1/invoices/render` with `{ source, format, theme? }`. Formats are `html`, `pdf`, or `png`; themes are `light` or `dark`. Decode each manifest file's `base64`, preserve ordered PNG pages, and verify its `bytes` and `sha256` before delivery.

## Preserve source fidelity

- **Payable currency:** if a table has several amount columns, exactly one qualified column matching `invoice.currency` is payable. With `currency: EUR`, `Amount (EUR)` is payable and `Amount (JPY)` is informational. If no qualifier matches, the final amount column is payable. Write conversions explicitly; ttyinv does not fetch exchange rates.
- **Authored summaries:** a row whose first/description cell is `Subtotal`, `Total`, or `Grand Total` must have an explicit numeric payable cell. It is preserved as a summary row but excluded from generated section and invoice totals. A numeric row without quantity/rate inputs is valid.
- **Recap tables:** set `summaryOnly: true` on a table section that repeats earlier amounts. REST and MCP emit `<!-- ttyinv:summary-only -->`; its rows remain visible, but the whole section contributes zero to generated invoice totals.
- **Page breaks:** set `pageBreakBefore: true` on a table or prose section in create input. REST and MCP emit the exact marker `<!-- ttyinv:page-break-before -->` immediately before its H2, and validation output returns `pageBreakBefore: true`; omitted or false emits no marker.

Use fabricated `example.com` parties when demonstrating or testing. On `401`, ask the user to create or replace a token at `/agents`; never request that they paste it into chat. On `402`, tell the user that hosted HTML, PDF, and PNG rendering requires an active lifetime purchase. On `422`, revise only the fields identified by diagnostics and retry once. On rate limits or server failures, stop and report the response rather than looping.