Invoice Tools

The MCP server has 10 tools for drafting invoices, managing line items, sending invoices, recording manual payments, and voiding invoices.

sendInvoice, markInvoicePaid, and voidInvoice default to Ask. In agent chat, you approve each call. The MCP server has no approval flow, so these tools are not exposed to MCP clients until you explicitly set their individual permissions to Allow. Allowing invoices:write does not enable them.

All other invoice tools default to Allow. Returned invoices omit publicToken, stripeInvoiceId, lastSyncedAt, and syncSource. Returned manual payments also omit customerTransactionId, stripePaymentIntentId, and idempotencyKey.

Invoices

createInvoice

Create a draft invoice header for a business and customer. Permission: invoices:write Parameters:

Name	Type	Required	Description
`businessId`	string (UUID)	Yes	Business issuing the invoice
`customerId`	string (UUID)	Yes	Customer being billed
`billToName`	string \| null	No	Billing recipient name
`billToEmail`	string \| null	No	Billing recipient email
`billToAddressLine1`	string \| null	No	Billing address line 1
`billToAddressLine2`	string \| null	No	Billing address line 2
`billToCity`	string \| null	No	Billing city
`billToState`	string \| null	No	Billing state or region
`billToPostalCode`	string \| null	No	Billing postal code
`billToCountry`	string \| null	No	Billing country
`dueAt`	string \| null	No	Due timestamp
`notes`	string \| null	No	Customer-facing notes; omit to use the business default, `null` for none
`terms`	string \| null	No	Payment terms; omit to use the business default, `null` for none
`data`	object \| null	No	Structured invoice data
`currency`	string	No	Lowercase ISO 4217 code; defaults to `usd`

Returns: The invoice with line items.

getInvoice

Get an invoice with its line items by ID. Permission: invoices:read Parameters:

Name	Type	Required	Description
`invoiceId`	string (UUID)	Yes	Invoice to retrieve

Returns: The invoice with line items, or null if it is not found.

listInvoices

List invoices with pagination and optional filters. Permission: invoices:read Parameters:

Name	Type	Required	Default	Description
`limit`	number	No	10	Number of invoices to return, up to 100
`offset`	number	No	0	Number of invoices to skip
`status`	string	No		`draft`, `open`, `paid`, `void`, or `uncollectible`
`customerId`	string (UUID)	No		Customer filter
`dueAfter`	string	No		Include invoices due at or after this ISO 8601 timestamp
`dueBefore`	string	No		Include invoices due at or before this ISO 8601 timestamp
`overdueOnly`	boolean	No	false	Include open invoices due before the call time

Returns: A paginated list of invoices with line items. When overdueOnly is true, omit status or set it to open.

updateInvoice

Update public fields on a draft invoice. Issued invoices cannot be edited with this tool. Permission: invoices:write Parameters:

Name	Type	Required	Description
`invoiceId`	string (UUID)	Yes	Draft invoice to update
`customerId`	string (UUID)	No	Replacement customer
`billToName`	string \| null	No	Billing recipient name
`billToEmail`	string \| null	No	Billing recipient email
`billToAddressLine1`	string \| null	No	Billing address line 1
`billToAddressLine2`	string \| null	No	Billing address line 2
`billToCity`	string \| null	No	Billing city
`billToState`	string \| null	No	Billing state or region
`billToPostalCode`	string \| null	No	Billing postal code
`billToCountry`	string \| null	No	Billing country
`dueAt`	string \| null	No	Due timestamp
`notes`	string \| null	No	Internal or customer-facing notes
`terms`	string \| null	No	Payment terms
`data`	object \| null	No	Structured invoice data
`currency`	string	No	Lowercase ISO 4217 currency code

Returns: The updated invoice with line items.

sendInvoice

Email an invoice to its customer from the business’s sending address. A draft is issued first, which freezes its bill-to details and moves it to open; an open invoice is sent again. The email goes to the invoice’s bill-to address, falling back to the customer’s. The wording comes from the organization’s Invoice email template, which is created on the first send. Permission: invoices.send:write (default level Ask — approval-gated in agent chat; over MCP, callable only at Allow) Parameters:

Name	Type	Required	Description
`invoiceId`	string (UUID)	Yes	Draft or open invoice to send
`idempotencyKey`	string	Yes	Retry key. Reuse it only to retry this exact send

Returns: The sent invoice with line items. A new key sends the invoice again — except after a send that failed, which a new key retries rather than delivering a second copy. Fails when the invoice has no email address to send to, or when no sending address is set up for invoices.

markInvoicePaid

Record an explicit manual payment against an invoice. Issue a draft before recording payment. Partial payments leave an open invoice open; cumulative payments move it to paid once they cover the invoice total. Permission: invoices.payments:write (default level Ask — approval-gated in agent chat; over MCP, callable only at Allow) Parameters:

Name	Type	Required	Description
`invoiceId`	string (UUID)	Yes	Invoice receiving the payment
`amountCents`	number	Yes	Positive integer amount in minor currency units
`idempotencyKey`	string	Yes	Retry key; reuse it only when retrying the same payment
`paidAt`	string	No	ISO 8601 payment time; defaults to the call time
`note`	string \| null	No	Note for the manual payment

Returns: The payment and refreshed invoice. The key is scoped to your organization and shared with the REST invoice-payment endpoint, chat, and automations. Retrying with the same key and the same details returns the original payment. Reusing that key for a different invoice, amount, time, or note fails instead, so record each new payment with a new key.

voidInvoice

Void an open invoice so it can no longer be collected or paid. Permission: invoices.void:write (default level Ask — approval-gated in agent chat; over MCP, callable only at Allow) Parameters:

Name	Type	Required	Description
`invoiceId`	string (UUID)	Yes	Open invoice to void

Returns: The voided invoice with line items.

Invoice line items

createInvoiceLineItem

Add a line item to a draft invoice. Permission: invoices:write Parameters:

Name	Type	Required	Description
`invoiceId`	string (UUID)	Yes	Draft invoice receiving the line item
`description`	string	Yes	Line item description
`quantity`	string	Yes	Decimal quantity with up to 4 fractional digits
`unitAmountCents`	number	Yes	Unit amount in whole minor currency units
`position`	number	No	Zero-based display position

Returns: The refreshed invoice with line items.

updateInvoiceLineItem

Update a draft invoice line item. Permission: invoices:write Parameters:

Name	Type	Required	Description
`lineItemId`	string (UUID)	Yes	Line item to update
`description`	string	No	Replacement line item description
`quantity`	string	No	Decimal quantity with up to 4 fractional digits
`unitAmountCents`	number	No	Replacement unit amount in minor units
`position`	number	No	Replacement zero-based display position

Returns: The refreshed invoice with line items.

deleteInvoiceLineItem

Delete a draft invoice line item. Permission: invoices:write Parameters:

Name	Type	Required	Description
`lineItemId`	string (UUID)	Yes	Line item to delete

Returns: The refreshed invoice with line items.

Getting Started

Agent resources

Invoices

createInvoice

getInvoice

listInvoices

updateInvoice

sendInvoice

markInvoicePaid

voidInvoice

Invoice line items

createInvoiceLineItem

updateInvoiceLineItem

deleteInvoiceLineItem

​Invoices

​createInvoice

​getInvoice

​listInvoices

​updateInvoice

​sendInvoice

​markInvoicePaid

​voidInvoice

​Invoice line items

​createInvoiceLineItem

​updateInvoiceLineItem

​deleteInvoiceLineItem

Invoices

createInvoice

getInvoice

listInvoices

updateInvoice

sendInvoice

markInvoicePaid

voidInvoice

Invoice line items

createInvoiceLineItem

updateInvoiceLineItem

deleteInvoiceLineItem