Invoices
Invoices tools exposed over the SuperBooks MCP API.
The invoices domain exposes 5 tools, 1 of which is destructive.
Destructive tools are only declared when the credential holds apis.all and the team has turned on destructive AI tools;
on a connection covering several teams, a call naming a team with the setting off is refused.
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 (one or several), date range (issue_date), and customer. Pass the returned nextCursor to fetch the next page. totals sums EVERY invoice matching the filters (not just this page), per status and currency, so use it for counts and amounts instead of adding up pages. Statuses: unpaid and overdue were sent and are money customers still owe (an overdue invoice is NOT also unpaid, so include both); draft and scheduled have not been sent, so the customer owes nothing yet. For 'outstanding' or 'who owes me' questions, pass statuses [unpaid, overdue, draft, scheduled] and report the amount owed separately from unsent drafts.
| Parameter | Type | Required | Description |
|---|---|---|---|
status | draft | overdue | paid | unpaid | canceled | scheduled | refunded | no | Filter by invoice status |
statuses | array of draft | overdue | paid | unpaid | canceled | scheduled | refunded | no | Match any of these statuses, e.g. [unpaid, overdue]. If status is also given, it is added to this list. |
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 (uuid) | no | Pagination cursor returned by the previous call |
limit | integer | no | Max items per page (1-100) Default: 25. |
invoices_send
Scope tier: write
Send a draft invoice to its customer: marks it sent (status draft -> unpaid; the schema has no 'sent' status) and queues the customer email. Sending an invoice that was already sent returns it with already_sent: true and does not email the customer again. Throws if the invoice is not found, is canceled or paid, or the email could not be queued (the invoice then stays a draft).
| 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. Only an unpaid, overdue or scheduled invoice can be voided: a paid invoice must be marked unpaid first, a refunded invoice can never be voided, and a draft is deleted rather than voided. Throws if the invoice is not found, is already canceled (so re-voiding never silently succeeds), or is in a status that cannot be voided.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | yes | Invoice ID to void |