Transactions
Transactions tools exposed over the SuperBooks MCP API.
The transactions 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
transactions_delete
Scope tier: destructive · Destructive — requires the two-gate check
Permanently delete a transaction. Destructive — confirm with the user before calling. Use update_status to 'archived' or 'excluded' for non-destructive removal. Returns deleted: false if the transaction was already absent — does not throw.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | yes | Transaction ID. This action is permanent. |
transactions_get
Scope tier: read
Fetch one transaction by ID with full details (counterparty, attachments, notes).
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | yes | Transaction ID |
transactions_list
Scope tier: read
List bank transactions for the current team, newest first. Supports cursor pagination plus filters by date range, status, category slug, and bank account. Pass the returned nextCursor to fetch the next page.
| Parameter | Type | Required | Description |
|---|---|---|---|
from | string | no | Inclusive lower bound, YYYY-MM-DD |
to | string | no | Inclusive upper bound, YYYY-MM-DD |
status | posted | pending | excluded | completed | archived | exported | no | Filter by workflow status |
category_slug | string | no | Filter by category slug |
bank_account_id | string (uuid) | no | Filter by bank account ID |
cursor | string | no | Pagination cursor returned by the previous call |
limit | integer | no | Max items per page (1-100) Default: 25. |
transactions_update_category
Scope tier: write
Assign a category slug to a transaction. The slug must already exist in the team's categories table — call categories_list first if you're unsure of valid slugs.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | yes | Transaction ID |
category_slug | string | yes | Category slug — must exist in this team's categories |
transactions_update_status
Scope tier: write
Update the workflow status of one transaction (posted | pending | excluded | completed | archived | exported). Use 'archived' or 'excluded' for non-destructive removal — DO NOT use transactions_delete unless the user explicitly asks for permanent deletion.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | yes | Transaction ID |
status | posted | pending | excluded | completed | archived | exported | yes | New status to assign |