Create Invoice
invoice_createCreates a new invoice for an existing client using provided line items, auto-calculates subtotal, tax, discount, and total, generates a sequential invoice number, and returns the full invoice object ready for sending.
Instructions
Create a new invoice for an existing client. Required: client_id (UUID) and line_items (non-empty array of {description, quantity, unit_price, tax_rate?, discount_percent?} — tax and discount are per-line). Optional: currency (defaults to the client's default_currency then USD), issue_date (YYYY-MM-DD or full ISO, defaults to today), due_date (same format, defaults to issue_date + 30 days), notes, and terms. Auto-calculates subtotal, discount_total, tax_total, and total; generates a sequential invoice_number in format INV-YYYY-NNNN; sets status="draft". Returns the full invoice object ready for invoice_send.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| notes | No | Free-text notes shown on the PDF (e.g. payment instructions, thank-you). | |
| terms | No | Free-text terms section on the PDF (e.g. "Net 30. Late fee 1.5%/mo."). | |
| currency | No | ISO 4217 code for the invoice. One of: USD, EUR, GBP, CAD, AUD, JPY, CHF, TRY, BRL, INR. Defaults to the client's default_currency, then USD. | |
| due_date | No | Payment due date — same format as issue_date. Defaults to issue_date + 30 days. Used by invoice_risk and overdue detection. | |
| client_id | Yes | UUID of the client this invoice is billed to. Must exist (created via client_manage). The stored client_email and client_name are snapshotted into the invoice at create time. | |
| issue_date | No | Invoice issue date — accepts either YYYY-MM-DD or full ISO-8601. Defaults to today (UTC). | |
| line_items | Yes | Non-empty array of line items. The invoice subtotal, tax_total, discount_total, and total are auto-computed by summing each item's (quantity × unit_price), then per-line discount, then per-line tax. |