Invoices
BlueSuite MCP tools for invoices
See connection and authentication and workflow rules before calling these tools.
Related REST API and behavior.
List invoices with optional pagination, search, and filters
| Field | Type / accepted values | Required | Details |
|---|
page | integer | No | Page number (default: 1) |
per_page | integer | No | Results per page (default: 25) minimum: 1. maximum: 100. |
search | string | No | Search invoices |
sort_by | "id", "number", "name", "status", "type", "total", "date", "due_date", "send_on", "created_at", "modified_at" | No | Field to sort by. Unknown values fall back to the default sort. |
sort_direction | "asc", "desc" | No | Sort direction |
contact_id | integer | No | Filter by contact ID |
job_id | JSON value | No | Filter by job ID |
exclude_children | boolean | No | Exclude child invoices (recurring children) |
exclude_statuses | array of "draft", "sent", "paid", "overdue", "cancelled", "partially_paid", "scheduled" | No | Exclude invoices with any of these statuses. |
tag_ids | array of JSON value | No | Filter to records carrying ANY of these tag IDs (not all). Use list_tags with the matching taggable_type to resolve tag names to IDs first. |
| Field | Type / accepted values | Required | Details |
|---|
data | array of object | Yes | The matching records for this page. |
pagination | object | No | How many more pages of results exist. Absent when the API returned an unpaged result. |
pagination.page | integer | When parent supplied | Current page number, 1-based. |
pagination.per_page | integer | When parent supplied | Number of results per page. |
pagination.total_pages | integer | When parent supplied | Total number of pages available. |
Create a new invoice
| Field | Type / accepted values | Required | Details |
|---|
name | string | No | Invoice name/title |
contact_id | integer | No | Associated contact ID |
property_id | JSON value | No | Associated property ID |
job_id | JSON value | No | Associated job ID |
quote_id | JSON value | No | Associated quote ID |
salesperson_id | string | No | UUID of salesperson. Use list_users to resolve names. Format: uuid. |
date | string | No | Invoice date (YYYY-MM-DD) |
due_date | JSON value | No | Due date (YYYY-MM-DD) |
send_on | JSON value | No | Scheduled send date (YYYY-MM-DD) |
message | string | No | Message to client |
payment_terms | "due_on_receipt", "net_7", "net_14", "net_30", "net_60", "net_90" | No | Payment terms (default: due_on_receipt) |
line_items | array of object or object | No | Array of line item objects. Two shapes are accepted: a regular priced row ({ name, quantity, unit_price }) or an inline image row ({ _type: "image", image_path, image_id, description }). For image rows: first call upload_file with module_type="workspace", category="line_item", is_public=true to upload the image, then pass the returned path as image_path and id as image_id. |
line_items[]._type | "lineItem" | No | For lineItem rows. Defaults to lineItem when omitted. |
line_items[].name | string | For this variant | For lineItem rows. Item name |
line_items[].description | string | No | For lineItem rows. Plain text description for this line item. Omit when not needed. Default: "". |
line_items[].quantity | number | No | For lineItem rows. Quantity Default: 1. |
line_items[].unit_price | number | For this variant | For lineItem rows. Price per unit |
line_items[].taxable | boolean | No | For lineItem rows. Whether the item is taxable |
line_items[].optional | boolean | No | For lineItem rows. Whether the item is optional |
line_items[]._type | "image" | For this variant | For image rows. |
line_items[].image_path | string | For this variant | For image rows. Storage path returned by a prior upload_file call. Upload with module_type="workspace", category="line_item", is_public=true to get a usable path. minLength: 1. |
line_items[].image_id | integer | No | For image rows. Upload link ID (id) returned by the same upload_file call. |
line_items[].description | string | No | For image rows. Caption shown beneath the image in the line items list. |
discount | number | No | Discount amount (default: 0) |
discount_unit | "percent", "amount" | No | How the discount is expressed. One of: 'percent' (a percentage of the subtotal) or 'amount' (a fixed currency amount). Default: 'percent'. |
deposit | number | No | Deposit amount (default: 0) |
deposit_unit | JSON value | No | How the deposit is expressed. One of: 'percent' or 'amount'. Default: 'percent'. |
tax_rate | number | No | Tax rate percentage (default: 0) |
tax_rate_id | JSON value | No | Tax rate preset ID |
total | number | No | Invoice total |
reminders_enabled | boolean | No | Whether BlueSuite automatically emails the client reminders about this invoice. Default: true. |
waive_credit_card_fee | JSON value | No | Skip the workspace's online processing fee for this record. Only meaningful when the workspace passes processing fees on to clients. Default: false. |
status | "draft", "sent", "paid", "overdue", "cancelled", "partially_paid", "scheduled" | No | Invoice status (default: draft). Record payments with create_payment; paid is rejected while a balance remains. |
type | "one-off", "recurring" | No | Invoice type. Only 'one-off' can be created, recurring invoices are no longer supported. For work that repeats, use setup_recurring_job instead; each completed visit bills as its own invoice. |
event_ids | array of JSON value | No | Event IDs to associate with this invoice |
custom_fields | object | No | Custom field values |
| Field | Type / accepted values | Required | Details |
|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
Get a single invoice by ID with expanded details, including the payments recorded against it and amount_due, what the client still owes. Use amount_due for balance questions rather than subtracting from total yourself; it is derived from the line items, and the stored total can be stale.
| Field | Type / accepted values | Required | Details |
|---|
id | integer | Yes | Invoice ID |
| Field | Type / accepted values | Required | Details |
|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
Update an existing invoice
| Field | Type / accepted values | Required | Details |
|---|
id | integer | Yes | Invoice ID |
name | string | No | Invoice name/title |
contact_id | JSON value | No | Associated contact ID |
property_id | JSON value | No | Associated property ID |
job_id | JSON value | No | Associated job ID |
quote_id | JSON value | No | Associated quote ID |
salesperson_id | string | No | UUID of salesperson. Use list_users to resolve names. Format: uuid. |
date | string | No | Invoice date (YYYY-MM-DD) |
due_date | JSON value | No | Due date (YYYY-MM-DD) |
send_on | JSON value | No | Scheduled send date (YYYY-MM-DD) |
message | string | No | Message to client |
payment_terms | "due_on_receipt", "net_7", "net_14", "net_30", "net_60", "net_90" | No | Payment terms |
line_items | array of object or object | No | Array of line item objects. Two shapes are accepted: a regular priced row ({ name, quantity, unit_price }) or an inline image row ({ _type: "image", image_path, image_id, description }). For image rows: first call upload_file with module_type="workspace", category="line_item", is_public=true to upload the image, then pass the returned path as image_path and id as image_id. |
line_items[]._type | "lineItem" | No | For lineItem rows. Defaults to lineItem when omitted. |
line_items[].name | string | For this variant | For lineItem rows. Item name |
line_items[].description | string | No | For lineItem rows. Plain text description for this line item. Omit when not needed. Default: "". |
line_items[].quantity | number | No | For lineItem rows. Quantity Default: 1. |
line_items[].unit_price | number | For this variant | For lineItem rows. Price per unit |
line_items[].taxable | boolean | No | For lineItem rows. Whether the item is taxable |
line_items[].optional | boolean | No | For lineItem rows. Whether the item is optional |
line_items[]._type | "image" | For this variant | For image rows. |
line_items[].image_path | string | For this variant | For image rows. Storage path returned by a prior upload_file call. Upload with module_type="workspace", category="line_item", is_public=true to get a usable path. minLength: 1. |
line_items[].image_id | integer | No | For image rows. Upload link ID (id) returned by the same upload_file call. |
line_items[].description | string | No | For image rows. Caption shown beneath the image in the line items list. |
discount | number | No | Discount amount |
discount_unit | "percent", "amount" | No | How the discount is expressed. One of: 'percent' (a percentage of the subtotal) or 'amount' (a fixed currency amount). |
deposit | number | No | Deposit amount |
deposit_unit | JSON value | No | How the deposit is expressed. One of: 'percent' or 'amount'. |
tax_rate | number | No | Tax rate percentage |
tax_rate_id | JSON value | No | Tax rate preset ID |
total | number | No | Invoice total |
reminders_enabled | boolean | No | Whether BlueSuite automatically emails the client reminders about this invoice. Default: true. |
waive_credit_card_fee | JSON value | No | Skip the workspace's online processing fee for this record. Only meaningful when the workspace passes processing fees on to clients. Default: false. |
status | "draft", "sent", "paid", "overdue", "cancelled", "partially_paid", "scheduled" | No | Invoice status. To mark paid, record a payment using create_payment with settle_remaining=true. |
type | "one-off", "recurring" | No | Invoice type |
event_ids | array of JSON value | No | Event IDs to associate |
custom_fields | object | No | Custom field values |
| Field | Type / accepted values | Required | Details |
|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
Delete an invoice by ID
| Field | Type / accepted values | Required | Details |
|---|
id | integer | Yes | Invoice ID |
| Field | Type / accepted values | Required | Details |
|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
Record a change to an invoice's status. This does NOT email anyone, marking an invoice "sent" sets its due date and notifies the business internally, but the client receives nothing. To actually deliver an invoice to the client, use send_notification with type="invoice_to_customer", which emails and texts the client according to the workspace notification settings and moves the invoice to sent. Use this tool for cancelling an invoice or correcting a status. To mark an invoice paid, use create_payment with object_type="invoice", category="payment", and settle_remaining=true. A paid status update is rejected if the invoice still has an outstanding balance.
| Field | Type / accepted values | Required | Details |
|---|
id | integer | Yes | Invoice ID |
status | "draft", "sent", "paid", "overdue", "cancelled", "partially_paid", "scheduled" | Yes | New status |
| Field | Type / accepted values | Required | Details |
|---|
data | object or null | Yes | The affected record, or the result of the operation. Null when nothing matched. |
The downloadable tool schemas include the full input and output contracts. Tables describe schema-level required fields; cross-field rules still apply.