Invoices
Invoices tools exposed over the SuperBooks MCP API.
The invoices domain exposes 5 tools, 1 of which is destructive.
Destructive tools are hidden from tools/list unless the credential holds
apis.all and the team has enabled destructive AI tools. See
Authentication.
Tools
invoices_create_draft
Scope tier: write
Create a draft invoice. Draft is not sent to the customer; user reviews and calls invoices_send to deliver.
| Parameter | Type | Required | Description |
|---|---|---|---|
customer_id | string (uuid) | yes | Customer ID — must already exist for this team |
currency | string | yes | 3-letter currency code (e.g., USD, EUR) |
issue_date | string | yes | Issue date, YYYY-MM-DD |
due_date | string | yes | Due date, YYYY-MM-DD |
line_items | array of object | yes | At least one line item; amount is computed from these |
note | string | no | Optional note shown on the invoice |
Each line_items entry:
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Line item name/description |
quantity | number | yes | Quantity (must be > 0) |
price | number | yes | Unit price per item (>= 0) |
invoices_get
Scope tier: read
Fetch one invoice with line items, customer, and totals.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | yes | Invoice ID |
invoices_list
Scope tier: read
List invoices for the current team, ordered by created_at desc (newest first). Supports cursor pagination plus filters by status, date range (issue_date), and customer. Pass the returned nextCursor to fetch the next page.
| Parameter | Type | Required | Description |
|---|---|---|---|
status | draft | overdue | paid | unpaid | canceled | scheduled | refunded | no | Filter by invoice status |
from | string | no | Inclusive lower bound on issue_date, YYYY-MM-DD |
to | string | no | Inclusive upper bound on issue_date, YYYY-MM-DD |
customer_id | string (uuid) | no | Filter by customer ID |
cursor | string | no | Pagination cursor returned by the previous call |
limit | integer | no | Max items per page (1-100) Default: 25. |
invoices_send
Scope tier: write
Mark a draft invoice as sent (status transitions draft -> unpaid; the schema does not have a 'sent' status). Triggers customer email delivery in the background. Throws if the invoice is not in 'draft' status.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | yes | Invoice ID to send |
invoices_void
Scope tier: destructive · Destructive — requires the two-gate check
Void an invoice (soft-cancel that preserves audit trail). Status becomes 'canceled' (the schema does not have a 'voided' status; canceled is the closest soft-cancel). Destructive — confirm with the user before calling. Throws if the invoice is not found OR is already canceled (so re-voiding never silently succeeds).
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | yes | Invoice ID to void |