Customers
Customers tools exposed over the SuperBooks MCP API.
The customers 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
customers_create
Scope tier: write
Create a new customer for the current team. Name and email are required; billing/shipping address fields and tags are optional. To assign tags, pass an array of existing tag ids (use tags_list/tags_create from the tags domain to manage them — this tool does NOT create new tags).
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | yes | Customer or organization name (e.g., 'Acme Corporation') |
email | string (email) | yes | Primary email address of the customer |
billingEmail | string (nullable) | no | Billing email address(es). Comma-separate multiple values (e.g., '[email protected], [email protected]'). |
phone | string (nullable) | no | Primary phone number |
website | string (nullable) | no | Website URL (e.g., 'https://acme.com') |
contact | string (nullable) | no | Primary contact person's name at the customer organization |
note | string (nullable) | no | Internal team-facing note about this customer |
vatNumber | string (nullable) | no | VAT (Value Added Tax) number |
country | string (nullable) | no | Country name (e.g., 'United States') |
countryCode | string (nullable) | no | Country code in ISO 3166-1 alpha-2 format (e.g., 'US') |
addressLine1 | string (nullable) | no | First line of the customer's address |
addressLine2 | string (nullable) | no | Second line of the customer's address (suite, apartment, etc.) |
city | string (nullable) | no | City |
state | string (nullable) | no | State or province |
zip | string (nullable) | no | ZIP or postal code |
preferred_currency | string (nullable) | no | 3-letter ISO currency code used as default for new invoices (e.g., 'USD'). Will be uppercased. |
default_payment_terms | integer (nullable) | no | Default payment terms in days used when generating invoices (e.g., 30 for net-30). |
tag_ids | array of string (uuid) | no | Array of existing tag ids to link to this customer. Tags must already exist for the team. |
customers_delete
Scope tier: destructive · Destructive — requires the two-gate check
Permanently delete a customer. DESTRUCTIVE: also permanently deletes all tracker projects belonging to this customer, and unlinks the customer from invoices and recurring-invoice schedules (those financial records are kept, but lose their customer link). Confirm with the user explicitly. Prefer customers_update with is_archived=true unless the customer must be removed for compliance reasons. Returns deleted: false if the customer was already absent — does not throw.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | yes | Customer ID. This action is permanent. |
customers_get
Scope tier: read
Fetch one customer by ID with full billing/shipping details, tags, and invoice/project counts. Returns null if not found for the current team.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | yes | Customer ID |
customers_list
Scope tier: read
List customers for the current team, newest first. Supports cursor pagination plus filters by name (partial, case-insensitive), email (partial, case-insensitive), tag id, and archived state. Pass the returned nextCursor to fetch the next page.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | no | Partial, case-insensitive match against the customer name |
email | string | no | Partial, case-insensitive match against the customer email |
tag_id | string (uuid) | no | Only return customers linked to this tag id. Use tags_list to find tag ids. |
is_archived | boolean | no | If true, only archived customers. If false, only non-archived (default behavior shows all). |
cursor | string | no | Pagination cursor returned by the previous call |
limit | integer | no | Max items per page (1-100) Default: 25. |
customers_update
Scope tier: write
Update one customer. Only the fields you pass are modified — other fields are left untouched. Set is_archived=true to archive (recommended over customers_delete for soft removal). If tag_ids is provided, it FULLY REPLACES the existing tag set: tags not in the array are unlinked. Omit tag_ids entirely to leave tags untouched.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | yes | Customer ID to update |
name | string | no | New customer name |
email | string (email) | no | New primary email |
billingEmail | string (nullable) | no | Billing email(s). Pass null to clear. Comma-separate for multiple. |
phone | string (nullable) | no | Phone number. Pass null to clear. |
website | string (nullable) | no | Website URL. Pass null to clear. |
contact | string (nullable) | no | Primary contact name. Pass null to clear. |
note | string (nullable) | no | Internal team-facing note. Pass null to clear. |
vatNumber | string (nullable) | no | VAT number. Pass null to clear. |
country | string (nullable) | no | Country name. Pass null to clear. |
countryCode | string (nullable) | no | Country code in ISO 3166-1 alpha-2 format. Pass null to clear. |
addressLine1 | string (nullable) | no | Address line 1. Pass null to clear. |
addressLine2 | string (nullable) | no | Address line 2. Pass null to clear. |
city | string (nullable) | no | City. Pass null to clear. |
state | string (nullable) | no | State or province. Pass null to clear. |
zip | string (nullable) | no | ZIP/postal code. Pass null to clear. |
preferred_currency | string (nullable) | no | 3-letter ISO currency code (uppercased). Pass null to clear. |
default_payment_terms | integer (nullable) | no | Default payment terms in days for new invoices. Pass null to clear. |
is_archived | boolean | no | Archive (true) or restore (false) the customer. Archived customers are hidden from default lists. |
tag_ids | array of string (uuid) | no | REPLACES the customer's tag set. Pass [] to clear all tags. Omit this field to leave existing tags untouched. Tags must already exist for the team. |