Books: sales

41 operations in the Tolvi API, version 1. Paths are relative to https://api.tolvi.co.uk. Every amount is integer pence.

Who owes the business money

GET/api/v1/books/sales/summary

Scopes: books:read

What is owed and overdue as at today, by customer (most overdue first), with drafts and reminders waiting for the owner. Part of the books product: the firm must have it and you must have access to it.

Responses

200 OK, `application/json`

Body: object (SalesSummary).

Who owes the business money, as at today.

200 OK response for GET /api/v1/books/sales/summary
Field	Type	Description
`asAt`required	`string (date)`	example "2026-03-31"
`owedPence`required	`integer`	Integer pence (GBP).
`overduePence`required	`integer`	Integer pence (GBP).
`unpaidInvoices`required	`integer`
`overdueInvoices`required	`integer`
`drafts`required	`integer`
`remindersToApprove`required	`integer`	Reminders waiting for the owner to approve.
`debtors`required	`array of SalesDebtor`	Most overdue first.
`debtors[].customerId`required	`string (uuid)`
`debtors[].customerName`required	`string`
`debtors[].owedPence`required	`integer`	Integer pence (GBP).
`debtors[].overduePence`required	`integer`	Integer pence (GBP).
`debtors[].invoices`required	`integer`
`debtors[].oldestDaysOverdue`required	`integer`	Days the oldest unpaid invoice is past due (0 if none is).

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

Get the invoice settings

GET/api/v1/books/sales/settings

Scopes: books:read

Address, contact and bank details printed on invoices, the brand colour and logo, VAT rounding, terms, numbering and reminders. Part of the books product: the firm must have it and you must have access to it.

Responses

200 OK, `application/json`

Body: object (SalesSettings).

What the business’s invoices say about it and how they look.

200 OK response for GET /api/v1/books/sales/settings
Field	Type	Description
`addressLines`required	`array of string`
`postcode`required	`string`nullable
`email`required	`string`nullable	Shown on invoices; customers’ replies go here.
`phone`required	`string`nullable
`ownerNames`required	`string`nullable	Sole traders and partnerships trading under a business name: the owner’s or partners’ names (Companies Act 2006 s1202).
`bankAccountName`required	`string`nullable
`bankSortCode`required	`string`nullable	example "123456"
`bankAccountNumber`required	`string`nullable	example "12345678"
`brandColour`required	`string`nullable	The accent colour on the business’s invoices; null for Tolvi’s. example "#1F4E79"
`logoStatus`required	`string (SalesLogoStatus)`	available: the logo is on invoices. pending_scan: a new logo is being checked for viruses. One of: `none`, `pending_scan`, `available`, `rejected`
`vatRounding`required	`string (VatRounding)`	VAT Notice 700 section 17: invoice (total VAT rounded down, para 17.5) or line (each line to the nearest penny, para 17.6). One of: `invoice`, `line`
`defaultTermsDays`required	`integer`	0 to 365
`footerNote`required	`string`nullable
`remindersOn`required	`boolean`	Draft reminders for overdue invoices. The owner still approves each one.
`invoicePrefix`required	`string`	example "INV-"
`creditNotePrefix`required	`string`	example "CN-"
`numberingChangeable`required	`boolean`	Whether the numbering can still change (nothing issued yet).

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

Change the invoice settings

PATCH/api/v1/books/sales/settings

Scopes: books:write

The business’s owners and admins, or a practice whose link can post. The numbering prefixes can change only until something has been issued (409 after), so numbers always run in one sequence. Part of the books product: the firm must have it and you must have access to it.

Request body

Required. application/json: object (SalesSettingsPatch).

Request body for PATCH /api/v1/books/sales/settings
Field	Type	Description
`addressLines`	`array of string`
`postcode`	`string`nullable
`email`	`string`nullable
`phone`	`string`nullable
`ownerNames`	`string`nullable
`bankAccountName`	`string`nullable
`bankSortCode`	`string`nullable
`bankAccountNumber`	`string`nullable
`brandColour`	`string`nullable
`vatRounding`	`string (VatRounding)`	VAT Notice 700 section 17: invoice (total VAT rounded down, para 17.5) or line (each line to the nearest penny, para 17.6). One of: `invoice`, `line`
`defaultTermsDays`	`integer`	0 to 365
`footerNote`	`string`nullable
`remindersOn`	`boolean`
`invoicePrefix`	`string`
`creditNotePrefix`	`string`

Responses

200 OK, `application/json`

Body: object (SalesSettings).

What the business’s invoices say about it and how they look.

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

Get a short-lived link to the logo

GET/api/v1/books/sales/settings/logo

Scopes: books:read

Null when there is no logo, or it is still being checked. Part of the books product: the firm must have it and you must have access to it.

Responses

200 OK, `application/json`

Body: object (SalesLogoLink).

200 OK response for GET /api/v1/books/sales/settings/logo
Field	Type	Description
`url`required	`string (uri)`nullable	A short-lived link to the logo, or null when there is none.
`contentType`required	`string`nullable

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

Start uploading a logo

POST/api/v1/books/sales/settings/logo

Scopes: books:write

A PNG or JPEG up to 512 KB. PUT the image to the URL with exactly the headers given, then call logo/complete. Part of the books product: the firm must have it and you must have access to it.

Request body

Required. application/json: object (SalesLogoUploadRequest).

Request body for POST /api/v1/books/sales/settings/logo
Field	Type	Description
`contentType`required	`string (SalesLogoType)`	One of: `image/png`, `image/jpeg`
`sizeBytes`required	`integer`	1 to 524288

Responses

200 OK, `application/json`

Body: object (SalesLogoUpload).

200 OK response for POST /api/v1/books/sales/settings/logo
Field	Type	Description
`upload`required	`object (PresignedUpload)`
`upload.url`required	`string (uri)`
`upload.method`required	`string (PresignedMethod)`	One of: `PUT`, `GET`
`upload.headers`required	`object`	Headers to send with the request.
`upload.expiresAt`required	`string (date-time)`

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

Take the logo off invoices

DELETE/api/v1/books/sales/settings/logo

Scopes: books:write

Part of the books product: the firm must have it and you must have access to it.

Responses

200 OK, `application/json`

Body: object (SalesSettings).

What the business’s invoices say about it and how they look.

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

Finish uploading a logo

POST/api/v1/books/sales/settings/logo/complete

Scopes: books:write

Checks the stored image and scans it for viruses. It goes on invoices once it is clean (logoStatus available). 422 if it is refused. Part of the books product: the firm must have it and you must have access to it.

Responses

200 OK, `application/json`

Body: object (SalesSettings).

What the business’s invoices say about it and how they look.

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

Get a customer’s statement

GET/api/v1/books/customers/{id}/statement

Scopes: books:read

Every issued invoice still owed at the date, with ageing that adds up to the total, and the email as it would go. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/customers/{id}/statement
Name	In	Type	Description
`id`required	path	`string (uuid)`
`asAt`	query	`string (date)`	Defaults to today.

Responses

200 OK, `application/json`

Body: object (SalesStatement).

What a customer owes at a date, invoice by invoice, with ageing.

200 OK response for GET /api/v1/books/customers/{id}/statement
Field	Type	Description
`customerId`required	`string (uuid)`
`customerName`required	`string`
`asAt`required	`string (date)`	example "2026-03-31"
`items`required	`array of SalesStatementItem`
`items[].documentId`required	`string (uuid)`
`items[].reference`required	`string`
`items[].date`required	`string (date)`	example "2026-03-31"
`items[].dueDate`required	`string (date)`nullable	example "2026-03-31"
`items[].daysOverdue`required	`integer`
`items[].bucket`required	`string`	example "days_1_30"
`items[].amountPence`required	`integer`	Integer pence (GBP).
`items[].openPence`required	`integer`	Integer pence (GBP).
`ageing`required	`object (SalesStatementAgeing)`
`ageing.current`required	`integer`
`ageing.days_1_30`required	`integer`
`ageing.days_31_60`required	`integer`
`ageing.days_61_90`required	`integer`
`ageing.over_90`required	`integer`
`totalPence`required	`integer`	Integer pence (GBP).
`emailDraft`required	`object (SalesStatementEmailDraft)`	The email as it would go, for the owner to read and change first.
`emailDraft.to`required	`string`nullable
`emailDraft.subject`required	`string`
`emailDraft.lines`required	`array of string`	The paragraphs of the email. A message of the owner’s own goes after the first.
`emailDraft.fileName`required	`string`
`lastSent`required	`object (SalesStatementSend)`nullable	The last time a statement was emailed to them.
`lastSent.sentTo`required	`string`
`lastSent.asAt`required	`string (date)`	example "2026-03-31"
`lastSent.totalPence`required	`integer`	Integer pence (GBP).
`lastSent.sentAt`required	`string (date-time)`

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Get a customer’s statement as a PDF

GET/api/v1/books/customers/{id}/statement/pdf

Scopes: books:read

As the customer receives it, with the business’s logo and colour. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/customers/{id}/statement/pdf
Name	In	Type	Description
`id`required	path	`string (uuid)`
`asAt`	query	`string (date)`	Defaults to today.

Responses

200 OK, `application/pdf`

The PDF

Body: string (binary).

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Email a customer their statement

POST/api/v1/books/customers/{id}/statement/send

Scopes: books:write
Access: A signed-in Tolvi session only, never an API token.

To the customer (or the address given), with the PDF attached, from Tolvi in the business’s name; replies go to the business. Only a person at the business, signed in: never an accountant in the books, an API client or an assistant. 409 if they owe nothing. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/customers/{id}/statement/send
Name	In	Type	Description
`id`required	path	`string (uuid)`

Request body

Optional. application/json: object (SalesStatementSendInput).

Request body for POST /api/v1/books/customers/{id}/statement/send
Field	Type	Description
`to`	`string`	Defaults to the customer’s email.
`subject`	`string`	up to 200 characters
`message`	`string`nullable	A short note added to the standard wording. up to 2000 characters
`asAt`	`string (date)`	Defaults to today. example "2026-03-31"

Responses

200 OK, `application/json`

Body: object (SalesStatement).

What a customer owes at a date, invoice by invoice, with ageing.

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

List customers

GET/api/v1/books/customers

Scopes: books:read

By name, with what each owes. archived=true lists archived customers instead. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/customers
Name	In	Type	Description
`archived`	query	`string`	One of: `true`, `false`
`search`	query	`any`

Responses

200 OK, `application/json`

Body: object (CustomerList).

200 OK response for GET /api/v1/books/customers
Field	Type	Description
`items`required	`array of Customer`
`items[].id`required	`string (uuid)`
`items[].name`required	`string`
`items[].email`required	`string`nullable
`items[].addressLines`required	`array of string`
`items[].postcode`required	`string`nullable
`items[].country`required	`string`	example "GB"
`items[].vatNumber`required	`string`nullable	Checked for format and check digits; only HMRC can confirm it is registered. example "GB123456789"
`items[].isBusiness`required	`boolean`
`items[].paymentTermsDays`required	`integer`nullable	Days to pay; null means the business’s usual terms.
`items[].cisRegistered`required	`boolean`
`items[].endUserOrIntermediary`required	`boolean`
`items[].remindersPaused`required	`boolean`
`items[].archived`required	`boolean`
`items[].owedPence`required	`integer`	Still owed on issued invoices, in pence.
`items[].overduePence`required	`integer`	Integer pence (GBP). Of that, past its due date.
`items[].createdAt`required	`string (date-time)`

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

Add a customer

POST/api/v1/books/customers

Scopes: books:write
Retries: Send an Idempotency-Key to make retries safe.

A UK VAT number must pass HMRC’s check digits (422 if not). Only HMRC can confirm a number is registered. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/customers
Name	In	Type	Description
`Idempotency-Key`	header	`string`	A unique key (1-255 visible characters) to make retries safe. Replayed for 24 hours. 1 to 255 characters

Request body

Required. application/json: object (CustomerInput).

Request body for POST /api/v1/books/customers
Field	Type	Description
`name`required	`string`	up to 200 characters
`email`	`string`nullable
`addressLines`	`array of string`
`postcode`	`string`nullable
`country`	`string`	example "GB"
`vatNumber`	`string`nullable
`isBusiness`	`boolean`
`paymentTermsDays`	`integer`nullable
`cisRegistered`	`boolean`
`endUserOrIntermediary`	`boolean`
`remindersPaused`	`boolean`

Responses

201 Created, `application/json`

Body: object (Customer).

Someone the business invoices.

201 Created response for POST /api/v1/books/customers
Field	Type	Description
`id`required	`string (uuid)`
`name`required	`string`
`email`required	`string`nullable
`addressLines`required	`array of string`
`postcode`required	`string`nullable
`country`required	`string`	example "GB"
`vatNumber`required	`string`nullable	Checked for format and check digits; only HMRC can confirm it is registered. example "GB123456789"
`isBusiness`required	`boolean`
`paymentTermsDays`required	`integer`nullable	Days to pay; null means the business’s usual terms.
`cisRegistered`required	`boolean`
`endUserOrIntermediary`required	`boolean`
`remindersPaused`required	`boolean`
`archived`required	`boolean`
`owedPence`required	`integer`	Still owed on issued invoices, in pence.
`overduePence`required	`integer`	Integer pence (GBP). Of that, past its due date.
`createdAt`required	`string (date-time)`

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 409 Conflict, 422 Unprocessable content, 429 Too many requests, as problem details (application/problem+json).

Get a customer

GET/api/v1/books/customers/{id}

Scopes: books:read

Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/customers/{id}
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (Customer).

Someone the business invoices.

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Change a customer

PATCH/api/v1/books/customers/{id}

Scopes: books:write

Invoices already issued keep the details they were issued with. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for PATCH /api/v1/books/customers/{id}
Name	In	Type	Description
`id`required	path	`string (uuid)`

Request body

Required. application/json: object (CustomerPatch).

Request body for PATCH /api/v1/books/customers/{id}
Field	Type	Description
`name`	`string`	up to 200 characters
`email`	`string`nullable
`addressLines`	`array of string`
`postcode`	`string`nullable
`country`	`string`
`vatNumber`	`string`nullable
`isBusiness`	`boolean`
`paymentTermsDays`	`integer`nullable
`cisRegistered`	`boolean`
`endUserOrIntermediary`	`boolean`
`remindersPaused`	`boolean`

Responses

200 OK, `application/json`

Body: object (Customer).

Someone the business invoices.

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Archive a customer

POST/api/v1/books/customers/{id}/archive

Scopes: books:write

Hidden from lists and new invoices. 409 while they still owe money. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/customers/{id}/archive
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (Customer).

Someone the business invoices.

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Restore an archived customer

POST/api/v1/books/customers/{id}/restore

Scopes: books:write

Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/customers/{id}/restore
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (Customer).

Someone the business invoices.

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

List invoices or credit notes

GET/api/v1/books/invoices

Scopes: books:read

Newest first. Status is worked out from payments and credit notes as at today. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/invoices
Name	In	Type	Description
`limit`	query	`integer`	1 to 500; default 200
`customerId`	query	`string (uuid)`
`status`	query	`string`	One of: `all`, `draft`, `unpaid`, `overdue`, `paid`, `void`
`kind`	query	`string`	One of: `invoice`, `credit_note`, `all`

Responses

200 OK, `application/json`

Body: object (SalesDocumentList).

200 OK response for GET /api/v1/books/invoices
Field	Type	Description
`items`required	`array of SalesDocument`
`items[].id`required	`string (uuid)`
`items[].kind`required	`string (SalesDocumentKind)`	One of: `invoice`, `credit_note`
`items[].state`required	`string (SalesDocumentState)`	draft: can be changed or deleted. issued: numbered, in the books and never changed. One of: `draft`, `issued`
`items[].status`required	`string (InvoiceStatus)`	draft, sent (issued, nothing paid yet), part_paid, paid, overdue, or void (credited in full). One of: `draft`, `sent`, `part_paid`, `paid`, `overdue`, `void`
`items[].number`required	`string`nullable	example "INV-0001"
`items[].opening`required	`boolean`	Issued before the books started and brought forward in the opening balances: it has its old number and no Tolvi copy to print or send.
`items[].customerId`required	`string (uuid)`
`items[].customerName`required	`string`
`items[].customerEmail`required	`string`nullable
`items[].issueDate`required	`string (date)`nullable	example "2026-03-31"
`items[].supplyDate`required	`string (date)`nullable	example "2026-03-31"
`items[].taxPoint`required	`string (date)`nullable	The VAT tax point (VATA 1994 s6). example "2026-03-31"
`items[].dueDate`required	`string (date)`nullable	example "2026-03-31"
`items[].termsDays`required	`integer`nullable
`items[].rounding`required	`string (VatRounding)`	VAT Notice 700 section 17: invoice (total VAT rounded down, para 17.5) or line (each line to the nearest penny, para 17.6). One of: `invoice`, `line`
`items[].reference`required	`string`nullable
`items[].purchaseOrder`required	`string`nullable
`items[].notes`required	`string`nullable
`items[].creditsId`required	`string (uuid)`nullable	Credit notes: the invoice credited.
`items[].creditsNumber`required	`string`nullable
`items[].reason`required	`string`nullable	Credit notes: why.
`items[].lines`required	`array of SalesLine`
`items[].lines[].description`required	`string`	up to 300 characters
`items[].lines[].quantity`	`string`	Up to 3 decimal places. Default 1. example "3"
`items[].lines[].unitPricePence`required	`integer`	Price per unit before VAT, in pence. at least 0
`items[].lines[].vatCode`required	`string (VatCode)`	One of: `S20`, `R5`, `Z0`, `EX`, `OS`, `RC_SERV`, `DRC_SALE`, `DRC_SALE_R5`, `DRC_PURCH`, `RC_GOODS_SALE`, `RC_GOODS_PURCH`, `PIVA`, `IMPORT_C79`, `BLOCKED`
`items[].lines[].accountId`	`string (uuid)`nullable	The income account; the business’s sales account when left out.
`items[].lines[].discount`	`object (SalesLineDiscount)`nullable
`items[].lines[].discount.kind`required	`string (SalesDiscountKind)`	One of: `percent`, `amount`
`items[].lines[].discount.bps`	`integer`	percent: basis points (1000 = 10%).
`items[].lines[].discount.pence`	`integer`	amount: pence off the line.
`items[].lines[].unitCode`	`string`nullable	UN/ECE Recommendation 20 unit code. example "DAY"
`items[].lines[].cisLabour`	`boolean`	CIS: labour (the deduction is worked on labour only).
`items[].lines[].netPence`required	`integer`	Integer pence (GBP). After any discount, before VAT.
`items[].lines[].vatPence`required	`integer`	Integer pence (GBP). VAT charged on the line (its share of the rounded total under invoice rounding).
`items[].lines[].rateBps`required	`integer`	Basis points (2000 = 20%).
`items[].totals`required	`object (SalesTotals)`
`items[].totals.netPence`required	`integer`	Integer pence (GBP).
`items[].totals.vatPence`required	`integer`	Integer pence (GBP).
`items[].totals.grossPence`required	`integer`	Integer pence (GBP).
`items[].totals.amountDuePence`required	`integer`	Integer pence (GBP). What the customer pays: the gross less any CIS deduction.
`items[].totals.notionalVatPence`required	`integer`	Integer pence (GBP).
`items[].totals.cisDeductionPence`required	`integer`	Integer pence (GBP).
`items[].totals.byVatCode`required	`array of SalesVatTotal`
`items[].totals.byVatCode[].code`required	`string (VatCode)`	One of: `S20`, `R5`, `Z0`, `EX`, `OS`, `RC_SERV`, `DRC_SALE`, `DRC_SALE_R5`, `DRC_PURCH`, `RC_GOODS_SALE`, `RC_GOODS_PURCH`, `PIVA`, `IMPORT_C79`, `BLOCKED`
`items[].totals.byVatCode[].rateBps`required	`integer`
`items[].totals.byVatCode[].netPence`required	`integer`	Integer pence (GBP).
`items[].totals.byVatCode[].vatPence`required	`integer`	Integer pence (GBP).
`items[].totals.byVatCode[].notionalVatPence`required	`integer`	Integer pence (GBP). Reverse charge: the VAT the customer accounts for, shown but not charged.
`items[].paidPence`required	`integer`	Integer pence (GBP).
`items[].creditedPence`required	`integer`	Integer pence (GBP).
`items[].outstandingPence`required	`integer`	Integer pence (GBP). Still owed (invoices); nil for drafts and credit notes.
`items[].daysOverdue`required	`integer`
`items[].sentAt`required	`string (date-time)`nullable
`items[].sentTo`required	`string`nullable
`items[].ledgerEntryId`required	`string (uuid)`nullable	The ledger entry it posted.
`items[].aiSuggestionId`required	`string (uuid)`nullable	Drafted from a sentence by Tolvi AI.
`items[].issuedAt`required	`string (date-time)`nullable
`items[].createdAt`required	`string (date-time)`
`items[].updatedAt`required	`string (date-time)`

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

Start a draft invoice

POST/api/v1/books/invoices

Scopes: books:write
Retries: Send an Idempotency-Key to make retries safe.

A draft posts nothing and can be changed or deleted. Pass the Tolvi AI suggestion’s id as aiSuggestionId when the draft came from a sentence; saving it records that the person accepted the suggestion. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/invoices
Name	In	Type	Description
`Idempotency-Key`	header	`string`	A unique key (1-255 visible characters) to make retries safe. Replayed for 24 hours. 1 to 255 characters

Request body

Required. application/json: object (CreateSalesDocument).

Request body for POST /api/v1/books/invoices
Field	Type	Description
`customerId`required	`string (uuid)`
`issueDate`	`string (date)`nullable	example "2026-03-31"
`supplyDate`	`string (date)`nullable	example "2026-03-31"
`dueDate`	`string (date)`nullable	example "2026-03-31"
`termsDays`	`integer`nullable
`lines`	`array of SalesLineInput`
`lines[].description`required	`string`	up to 300 characters
`lines[].quantity`	`string`	Up to 3 decimal places. Default 1. example "3"
`lines[].unitPricePence`required	`integer`	Price per unit before VAT, in pence. at least 0
`lines[].vatCode`required	`string (VatCode)`	One of: `S20`, `R5`, `Z0`, `EX`, `OS`, `RC_SERV`, `DRC_SALE`, `DRC_SALE_R5`, `DRC_PURCH`, `RC_GOODS_SALE`, `RC_GOODS_PURCH`, `PIVA`, `IMPORT_C79`, `BLOCKED`
`lines[].accountId`	`string (uuid)`nullable	The income account; the business’s sales account when left out.
`lines[].discount`	`object (SalesLineDiscount)`nullable
`lines[].discount.kind`required	`string (SalesDiscountKind)`	One of: `percent`, `amount`
`lines[].discount.bps`	`integer`	percent: basis points (1000 = 10%).
`lines[].discount.pence`	`integer`	amount: pence off the line.
`lines[].unitCode`	`string`nullable	UN/ECE Recommendation 20 unit code. example "DAY"
`lines[].cisLabour`	`boolean`	CIS: labour (the deduction is worked on labour only).
`reference`	`string`nullable
`purchaseOrder`	`string`nullable
`notes`	`string`nullable
`aiSuggestionId`	`string (uuid)`nullable	The Tolvi AI suggestion it was drafted from.

Responses

201 Created, `application/json`

Body: object (SalesDocumentDetail).

201 Created response for POST /api/v1/books/invoices
Field	Type	Description
`id`required	`string (uuid)`
`kind`required	`string (SalesDocumentKind)`	One of: `invoice`, `credit_note`
`state`required	`string (SalesDocumentState)`	draft: can be changed or deleted. issued: numbered, in the books and never changed. One of: `draft`, `issued`
`status`required	`string (InvoiceStatus)`	draft, sent (issued, nothing paid yet), part_paid, paid, overdue, or void (credited in full). One of: `draft`, `sent`, `part_paid`, `paid`, `overdue`, `void`
`number`required	`string`nullable	example "INV-0001"
`opening`required	`boolean`	Issued before the books started and brought forward in the opening balances: it has its old number and no Tolvi copy to print or send.
`customerId`required	`string (uuid)`
`customerName`required	`string`
`customerEmail`required	`string`nullable
`issueDate`required	`string (date)`nullable	example "2026-03-31"
`supplyDate`required	`string (date)`nullable	example "2026-03-31"
`taxPoint`required	`string (date)`nullable	The VAT tax point (VATA 1994 s6). example "2026-03-31"
`dueDate`required	`string (date)`nullable	example "2026-03-31"
`termsDays`required	`integer`nullable
`rounding`required	`string (VatRounding)`	VAT Notice 700 section 17: invoice (total VAT rounded down, para 17.5) or line (each line to the nearest penny, para 17.6). One of: `invoice`, `line`
`reference`required	`string`nullable
`purchaseOrder`required	`string`nullable
`notes`required	`string`nullable
`creditsId`required	`string (uuid)`nullable	Credit notes: the invoice credited.
`creditsNumber`required	`string`nullable
`reason`required	`string`nullable	Credit notes: why.
`lines`required	`array of SalesLine`
`lines[].description`required	`string`	up to 300 characters
`lines[].quantity`	`string`	Up to 3 decimal places. Default 1. example "3"
`lines[].unitPricePence`required	`integer`	Price per unit before VAT, in pence. at least 0
`lines[].vatCode`required	`string (VatCode)`	One of: `S20`, `R5`, `Z0`, `EX`, `OS`, `RC_SERV`, `DRC_SALE`, `DRC_SALE_R5`, `DRC_PURCH`, `RC_GOODS_SALE`, `RC_GOODS_PURCH`, `PIVA`, `IMPORT_C79`, `BLOCKED`
`lines[].accountId`	`string (uuid)`nullable	The income account; the business’s sales account when left out.
`lines[].discount`	`object (SalesLineDiscount)`nullable
`lines[].discount.kind`required	`string (SalesDiscountKind)`	One of: `percent`, `amount`
`lines[].discount.bps`	`integer`	percent: basis points (1000 = 10%).
`lines[].discount.pence`	`integer`	amount: pence off the line.
`lines[].unitCode`	`string`nullable	UN/ECE Recommendation 20 unit code. example "DAY"
`lines[].cisLabour`	`boolean`	CIS: labour (the deduction is worked on labour only).
`lines[].netPence`required	`integer`	Integer pence (GBP). After any discount, before VAT.
`lines[].vatPence`required	`integer`	Integer pence (GBP). VAT charged on the line (its share of the rounded total under invoice rounding).
`lines[].rateBps`required	`integer`	Basis points (2000 = 20%).
`totals`required	`object (SalesTotals)`
`totals.netPence`required	`integer`	Integer pence (GBP).
`totals.vatPence`required	`integer`	Integer pence (GBP).
`totals.grossPence`required	`integer`	Integer pence (GBP).
`totals.amountDuePence`required	`integer`	Integer pence (GBP). What the customer pays: the gross less any CIS deduction.
`totals.notionalVatPence`required	`integer`	Integer pence (GBP).
`totals.cisDeductionPence`required	`integer`	Integer pence (GBP).
`totals.byVatCode`required	`array of SalesVatTotal`
`totals.byVatCode[].code`required	`string (VatCode)`	One of: `S20`, `R5`, `Z0`, `EX`, `OS`, `RC_SERV`, `DRC_SALE`, `DRC_SALE_R5`, `DRC_PURCH`, `RC_GOODS_SALE`, `RC_GOODS_PURCH`, `PIVA`, `IMPORT_C79`, `BLOCKED`
`totals.byVatCode[].rateBps`required	`integer`
`totals.byVatCode[].netPence`required	`integer`	Integer pence (GBP).
`totals.byVatCode[].vatPence`required	`integer`	Integer pence (GBP).
`totals.byVatCode[].notionalVatPence`required	`integer`	Integer pence (GBP). Reverse charge: the VAT the customer accounts for, shown but not charged.
`paidPence`required	`integer`	Integer pence (GBP).
`creditedPence`required	`integer`	Integer pence (GBP).
`outstandingPence`required	`integer`	Integer pence (GBP). Still owed (invoices); nil for drafts and credit notes.
`daysOverdue`required	`integer`
`sentAt`required	`string (date-time)`nullable
`sentTo`required	`string`nullable
`ledgerEntryId`required	`string (uuid)`nullable	The ledger entry it posted.
`aiSuggestionId`required	`string (uuid)`nullable	Drafted from a sentence by Tolvi AI.
`issuedAt`required	`string (date-time)`nullable
`createdAt`required	`string (date-time)`
`updatedAt`required	`string (date-time)`
`supplier`required	`object (SalesParty)`	A business or customer as the document shows it (frozen at issue).
`supplier.name`required	`string`
`supplier.addressLines`required	`array of string`
`supplier.postcode`required	`string`nullable
`supplier.vatNumber`required	`string`nullable
`supplier.email`required	`string`nullable
`supplier.registeredName`required	`string`nullable	Companies and LLPs: the registered name.
`supplier.companyNumber`required	`string`nullable
`supplier.payTo`required	`string`nullable	How to pay, as printed (the business only).
`customer`required	`object (SalesParty)`	A business or customer as the document shows it (frozen at issue).
`customer.name`required	`string`
`customer.addressLines`required	`array of string`
`customer.postcode`required	`string`nullable
`customer.vatNumber`required	`string`nullable
`customer.email`required	`string`nullable
`customer.registeredName`required	`string`nullable	Companies and LLPs: the registered name.
`customer.companyNumber`required	`string`nullable
`customer.payTo`required	`string`nullable	How to pay, as printed (the business only).
`problems`required	`array of SalesProblem`	Drafts: what stops it being issued (errors) and what to check (warnings).
`problems[].code`required	`string`	example "customer_address_missing"
`problems[].severity`required	`string (SalesProblemSeverity)`	One of: `error`, `warning`
`problems[].field`required	`string`nullable	example "customer.address"
`problems[].message`required	`string`
`problems[].citation`required	`string`nullable	The legislation or HMRC guidance.
`payments`required	`array of SalesPayment`
`payments[].id`required	`string (uuid)`
`payments[].paidOn`required	`string (date)`	example "2026-03-31"
`payments[].amountPence`required	`integer`	Integer pence (GBP).
`payments[].method`required	`string (SalesPaymentMethod)`	One of: `bank_transfer`, `card`, `cash`, `cheque`, `other`
`payments[].accountId`required	`string (uuid)`
`payments[].reference`required	`string`nullable
`payments[].bankLineId`required	`string (uuid)`nullable	Set when it came from a matched bank line.
`payments[].ledgerEntryId`required	`string (uuid)`
`payments[].createdAt`required	`string (date-time)`
`creditNotes`required	`array of SalesCreditApplied`
`creditNotes[].id`required	`string (uuid)`
`creditNotes[].number`required	`string`nullable
`creditNotes[].state`required	`string (SalesDocumentState)`	draft: can be changed or deleted. issued: numbered, in the books and never changed. One of: `draft`, `issued`
`creditNotes[].issueDate`required	`string (date)`nullable	example "2026-03-31"
`creditNotes[].amountPence`required	`integer`	Integer pence (GBP). What it takes off the invoice.
`creditNotes[].reason`required	`string`nullable
`sends`required	`array of SalesSend`
`sends[].kind`required	`string (SalesSendKind)`	One of: `invoice`, `credit_note`, `reminder`
`sends[].sentTo`required	`string`
`sends[].subject`required	`string`
`sends[].sentAt`required	`string (date-time)`
`reminders`required	`array of SalesReminder`
`reminders[].id`required	`string (uuid)`
`reminders[].invoiceId`required	`string (uuid)`
`reminders[].invoiceNumber`required	`string`
`reminders[].customerName`required	`string`
`reminders[].customerEmail`required	`string`nullable
`reminders[].tone`required	`string (ReminderTone)`	One of: `friendly`, `firm`, `final`
`reminders[].daysOverdue`required	`integer`	Negative before the due date.
`reminders[].outstandingPence`required	`integer`	Integer pence (GBP).
`reminders[].compensationPence`required	`integer`	Integer pence (GBP). Fixed late payment compensation the owner may add (Late Payment of Commercial Debts (Interest) Act 1998 s5A); not added unless they choose to.
`reminders[].subject`required	`string`
`reminders[].body`required	`string`
`reminders[].status`required	`string (ReminderStatus)`	One of: `to_approve`, `sent`, `dismissed`
`reminders[].draftedOn`required	`string (date)`	example "2026-03-31"
`reminders[].sentAt`required	`string (date-time)`nullable
`reminders[].sentTo`required	`string`nullable

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 409 Conflict, 422 Unprocessable content, 429 Too many requests, as problem details (application/problem+json).

Draft an invoice from a sentence (Tolvi AI)

POST/api/v1/books/invoices/draft-from-sentence

Scopes: books:write

Tolvi AI reads a sentence such as "Invoice Acme for 3 days’ consulting at £450 plus VAT" and Tolvi builds a draft from your customers, VAT status and terms, with the questions to answer. A suggestion only: nothing is saved, issued or sent. Included in the Tolvi Books price. Needs a person; not available through MCP. Part of the books product: the firm must have it and you must have access to it.

Request body

Required. application/json: object (DraftInvoiceFromSentence).

Request body for POST /api/v1/books/invoices/draft-from-sentence
Field	Type	Description
`sentence`required	`string`	up to 1000 characters; example "Invoice Acme for 3 days' consulting at £450 plus VAT"

Responses

200 OK, `application/json`

Body: object (SalesDraftSuggestion).

What Tolvi AI made of the sentence: a suggestion to check and save as a draft. Nothing is saved, issued or sent.

200 OK response for POST /api/v1/books/invoices/draft-from-sentence
Field	Type	Description
`suggestionId`required	`string (uuid)`	The Tolvi AI suggestion; pass it as aiSuggestionId when saving the draft.
`customerMatch`required	`string (SalesCustomerMatch)`	One of: `existing`, `new`, `ambiguous`, `missing`
`customerId`required	`string (uuid)`nullable
`customerName`required	`string`nullable
`customerEmail`required	`string`nullable
`lines`required	`array of SalesLine`
`lines[].description`required	`string`	up to 300 characters
`lines[].quantity`	`string`	Up to 3 decimal places. Default 1. example "3"
`lines[].unitPricePence`required	`integer`	Price per unit before VAT, in pence. at least 0
`lines[].vatCode`required	`string (VatCode)`	One of: `S20`, `R5`, `Z0`, `EX`, `OS`, `RC_SERV`, `DRC_SALE`, `DRC_SALE_R5`, `DRC_PURCH`, `RC_GOODS_SALE`, `RC_GOODS_PURCH`, `PIVA`, `IMPORT_C79`, `BLOCKED`
`lines[].accountId`	`string (uuid)`nullable	The income account; the business’s sales account when left out.
`lines[].discount`	`object (SalesLineDiscount)`nullable
`lines[].discount.kind`required	`string (SalesDiscountKind)`	One of: `percent`, `amount`
`lines[].discount.bps`	`integer`	percent: basis points (1000 = 10%).
`lines[].discount.pence`	`integer`	amount: pence off the line.
`lines[].unitCode`	`string`nullable	UN/ECE Recommendation 20 unit code. example "DAY"
`lines[].cisLabour`	`boolean`	CIS: labour (the deduction is worked on labour only).
`lines[].netPence`required	`integer`	Integer pence (GBP). After any discount, before VAT.
`lines[].vatPence`required	`integer`	Integer pence (GBP). VAT charged on the line (its share of the rounded total under invoice rounding).
`lines[].rateBps`required	`integer`	Basis points (2000 = 20%).
`issueDate`required	`string (date)`	example "2026-03-31"
`supplyDate`required	`string (date)`nullable	example "2026-03-31"
`dueDate`required	`string (date)`nullable	example "2026-03-31"
`termsDays`required	`integer`nullable
`purchaseOrder`required	`string`nullable
`totals`required	`object (SalesTotals)`
`totals.netPence`required	`integer`	Integer pence (GBP).
`totals.vatPence`required	`integer`	Integer pence (GBP).
`totals.grossPence`required	`integer`	Integer pence (GBP).
`totals.amountDuePence`required	`integer`	Integer pence (GBP). What the customer pays: the gross less any CIS deduction.
`totals.notionalVatPence`required	`integer`	Integer pence (GBP).
`totals.cisDeductionPence`required	`integer`	Integer pence (GBP).
`totals.byVatCode`required	`array of SalesVatTotal`
`totals.byVatCode[].code`required	`string (VatCode)`	One of: `S20`, `R5`, `Z0`, `EX`, `OS`, `RC_SERV`, `DRC_SALE`, `DRC_SALE_R5`, `DRC_PURCH`, `RC_GOODS_SALE`, `RC_GOODS_PURCH`, `PIVA`, `IMPORT_C79`, `BLOCKED`
`totals.byVatCode[].rateBps`required	`integer`
`totals.byVatCode[].netPence`required	`integer`	Integer pence (GBP).
`totals.byVatCode[].vatPence`required	`integer`	Integer pence (GBP).
`totals.byVatCode[].notionalVatPence`required	`integer`	Integer pence (GBP). Reverse charge: the VAT the customer accounts for, shown but not charged.
`questions`required	`array of SalesDraftQuestion`
`questions[].code`required	`string`	example "customer_ambiguous"
`questions[].field`required	`string`
`questions[].message`required	`string`
`questions[].blocking`required	`boolean`	Must be answered before the invoice can be issued.
`questions[].options`required	`array of object`
`questions[].options[].id`required	`string`
`questions[].options[].label`required	`string`
`assumptions`required	`array of SalesDraftAssumption`
`assumptions[].field`required	`string`
`assumptions[].message`required	`string`
`note`required	`string`	Tolvi AI’s note on anything unclear, or "".

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

Get an invoice or credit note

GET/api/v1/books/invoices/{id}

Scopes: books:read

With its lines, totals, what is owed, payments, credit notes, emails sent and reminders. A draft lists what would stop it being issued. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/invoices/{id}
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (SalesDocumentDetail).

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Change a draft

PATCH/api/v1/books/invoices/{id}

Scopes: books:write

409 once issued: an issued invoice is corrected with a credit note. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for PATCH /api/v1/books/invoices/{id}
Name	In	Type	Description
`id`required	path	`string (uuid)`

Request body

Required. application/json: object (UpdateSalesDocument).

Change a draft. Fields left out keep their value.

Request body for PATCH /api/v1/books/invoices/{id}
Field	Type	Description
`customerId`	`string (uuid)`
`issueDate`	`string (date)`nullable	example "2026-03-31"
`supplyDate`	`string (date)`nullable	example "2026-03-31"
`dueDate`	`string (date)`nullable	example "2026-03-31"
`termsDays`	`integer`nullable
`lines`	`array of SalesLineInput`
`lines[].description`required	`string`	up to 300 characters
`lines[].quantity`	`string`	Up to 3 decimal places. Default 1. example "3"
`lines[].unitPricePence`required	`integer`	Price per unit before VAT, in pence. at least 0
`lines[].vatCode`required	`string (VatCode)`	One of: `S20`, `R5`, `Z0`, `EX`, `OS`, `RC_SERV`, `DRC_SALE`, `DRC_SALE_R5`, `DRC_PURCH`, `RC_GOODS_SALE`, `RC_GOODS_PURCH`, `PIVA`, `IMPORT_C79`, `BLOCKED`
`lines[].accountId`	`string (uuid)`nullable	The income account; the business’s sales account when left out.
`lines[].discount`	`object (SalesLineDiscount)`nullable
`lines[].discount.kind`required	`string (SalesDiscountKind)`	One of: `percent`, `amount`
`lines[].discount.bps`	`integer`	percent: basis points (1000 = 10%).
`lines[].discount.pence`	`integer`	amount: pence off the line.
`lines[].unitCode`	`string`nullable	UN/ECE Recommendation 20 unit code. example "DAY"
`lines[].cisLabour`	`boolean`	CIS: labour (the deduction is worked on labour only).
`reference`	`string`nullable
`purchaseOrder`	`string`nullable
`notes`	`string`nullable
`reason`	`string`nullable	Credit notes: why.

Responses

200 OK, `application/json`

Body: object (SalesDocumentDetail).

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Delete a draft

DELETE/api/v1/books/invoices/{id}

Scopes: books:write

409 once issued: an issued invoice is never deleted, only cancelled with a credit note. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for DELETE /api/v1/books/invoices/{id}
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

204 No content

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Copy an invoice as a new draft

POST/api/v1/books/invoices/{id}/duplicate

Scopes: books:write
Retries: Send an Idempotency-Key to make retries safe.

A new draft for the same customer with the same lines and note, undated (it takes the date it is issued) and on the customer’s usual terms. The order number isn’t copied. Credit notes can’t be copied. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/invoices/{id}/duplicate
Name	In	Type	Description
`id`required	path	`string (uuid)`
`Idempotency-Key`	header	`string`	A unique key (1-255 visible characters) to make retries safe. Replayed for 24 hours. 1 to 255 characters

Responses

201 Created, `application/json`

Body: object (SalesDocumentDetail).

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 409 Conflict, 422 Unprocessable content, 429 Too many requests, as problem details (application/problem+json).

Issue an invoice or credit note

POST/api/v1/books/invoices/{id}/issue

Scopes: books:write

Takes the next number in the series (no gaps: VAT Regulations 1995 reg 14(1)(a)) and posts it to the books, in one step. 422 with every reason when it can’t be issued (for example a missing customer address on a VAT invoice, or a locked period); nothing is numbered or posted then. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/invoices/{id}/issue
Name	In	Type	Description
`id`required	path	`string (uuid)`

Request body

Optional. application/json: object (IssueSalesDocument).

Request body for POST /api/v1/books/invoices/{id}/issue
Field	Type	Description
`issueDate`	`string (date)`	Defaults to the draft’s date, or today. example "2026-03-31"

Responses

200 OK, `application/json`

Body: object (SalesDocumentDetail).

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Draft a credit note for an issued invoice

POST/api/v1/books/invoices/{id}/credit-notes

Scopes: books:write
Retries: Send an Idempotency-Key to make retries safe.

The whole invoice unless lines are given, at the VAT rates of the original supply (VAT Notice 700 section 19). Issue the credit note to post it. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/invoices/{id}/credit-notes
Name	In	Type	Description
`id`required	path	`string (uuid)`
`Idempotency-Key`	header	`string`	A unique key (1-255 visible characters) to make retries safe. Replayed for 24 hours. 1 to 255 characters

Request body

Required. application/json: object (CreditNoteRequest).

Request body for POST /api/v1/books/invoices/{id}/credit-notes
Field	Type	Description
`reason`required	`string`	up to 300 characters
`lines`	`array of SalesLineInput`	Leave out to credit the whole invoice.
`lines[].description`required	`string`	up to 300 characters
`lines[].quantity`	`string`	Up to 3 decimal places. Default 1. example "3"
`lines[].unitPricePence`required	`integer`	Price per unit before VAT, in pence. at least 0
`lines[].vatCode`required	`string (VatCode)`	One of: `S20`, `R5`, `Z0`, `EX`, `OS`, `RC_SERV`, `DRC_SALE`, `DRC_SALE_R5`, `DRC_PURCH`, `RC_GOODS_SALE`, `RC_GOODS_PURCH`, `PIVA`, `IMPORT_C79`, `BLOCKED`
`lines[].accountId`	`string (uuid)`nullable	The income account; the business’s sales account when left out.
`lines[].discount`	`object (SalesLineDiscount)`nullable
`lines[].discount.kind`required	`string (SalesDiscountKind)`	One of: `percent`, `amount`
`lines[].discount.bps`	`integer`	percent: basis points (1000 = 10%).
`lines[].discount.pence`	`integer`	amount: pence off the line.
`lines[].unitCode`	`string`nullable	UN/ECE Recommendation 20 unit code. example "DAY"
`lines[].cisLabour`	`boolean`	CIS: labour (the deduction is worked on labour only).
`issueDate`	`string (date)`	example "2026-03-31"

Responses

201 Created, `application/json`

Body: object (SalesDocumentDetail).

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 409 Conflict, 422 Unprocessable content, 429 Too many requests, as problem details (application/problem+json).

Cancel an issued invoice

POST/api/v1/books/invoices/{id}/void

Scopes: books:write
Retries: Send an Idempotency-Key to make retries safe.

Issues a credit note for the whole invoice, so its number stays used and the books balance. 409 if anything has been paid or credited already (use a credit note instead). Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/invoices/{id}/void
Name	In	Type	Description
`id`required	path	`string (uuid)`
`Idempotency-Key`	header	`string`	A unique key (1-255 visible characters) to make retries safe. Replayed for 24 hours. 1 to 255 characters

Request body

Required. application/json: object (VoidInvoiceRequest).

Request body for POST /api/v1/books/invoices/{id}/void
Field	Type	Description
`reason`required	`string`	up to 300 characters
`issueDate`	`string (date)`	example "2026-03-31"

Responses

200 OK, `application/json`

Body: object (SalesDocumentDetail).

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 409 Conflict, 422 Unprocessable content, 429 Too many requests, as problem details (application/problem+json).

Record a payment received

POST/api/v1/books/invoices/{id}/payments

Scopes: books:write
Retries: Send an Idempotency-Key to make retries safe.

Posts it to the books (into the bank or cash account given, out of money owed to you). No more than is still owed; not dated in the future. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/invoices/{id}/payments
Name	In	Type	Description
`id`required	path	`string (uuid)`
`Idempotency-Key`	header	`string`	A unique key (1-255 visible characters) to make retries safe. Replayed for 24 hours. 1 to 255 characters

Request body

Required. application/json: object (RecordSalesPayment).

Request body for POST /api/v1/books/invoices/{id}/payments
Field	Type	Description
`paidOn`required	`string (date)`	example "2026-03-31"
`amountPence`required	`integer`	Integer pence (GBP). at least 1
`method`	`string (SalesPaymentMethod)`	One of: `bank_transfer`, `card`, `cash`, `cheque`, `other`
`accountId`required	`string (uuid)`	The bank or cash account the money went into.
`reference`	`string`nullable

Responses

201 Created, `application/json`

Body: object (SalesDocumentDetail).

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 409 Conflict, 422 Unprocessable content, 429 Too many requests, as problem details (application/problem+json).

Get the PDF

GET/api/v1/books/invoices/{id}/pdf

Scopes: books:read

As the customer receives it, with the business’s logo and colour. A draft is marked DRAFT. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/invoices/{id}/pdf
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK, `application/pdf`

The PDF

Body: string (binary).

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Email an issued invoice or credit note

POST/api/v1/books/invoices/{id}/send

Scopes: books:write
Access: A signed-in Tolvi session only, never an API token.

To the customer (or the address given), with the PDF attached, from Tolvi in the business’s name; replies go to the business. Only a person at the business, signed in: never an accountant in the books, an API client or an assistant. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/invoices/{id}/send
Name	In	Type	Description
`id`required	path	`string (uuid)`

Request body

Optional. application/json: object (SendSalesDocument).

Request body for POST /api/v1/books/invoices/{id}/send
Field	Type	Description
`to`	`string`	Defaults to the customer’s email.
`subject`	`string`	The email’s subject. Defaults to "Invoice INV-0001 from <business>" (or "Credit note …"). up to 200 characters
`message`	`string`nullable	up to 2000 characters

Responses

200 OK, `application/json`

Body: object (SalesDocumentDetail).

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

List payment reminders

GET/api/v1/books/reminders

Scopes: books:read

Drafted by Tolvi for overdue (or nearly due) invoices; nothing is sent until a person at the business approves it. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/reminders
Name	In	Type	Description
`invoiceId`	query	`string (uuid)`
`status`	query	`string`	One of: `to_approve`, `sent`, `dismissed`, `all`

Responses

200 OK, `application/json`

Body: object (SalesReminderList).

200 OK response for GET /api/v1/books/reminders
Field	Type	Description
`items`required	`array of SalesReminder`
`items[].id`required	`string (uuid)`
`items[].invoiceId`required	`string (uuid)`
`items[].invoiceNumber`required	`string`
`items[].customerName`required	`string`
`items[].customerEmail`required	`string`nullable
`items[].tone`required	`string (ReminderTone)`	One of: `friendly`, `firm`, `final`
`items[].daysOverdue`required	`integer`	Negative before the due date.
`items[].outstandingPence`required	`integer`	Integer pence (GBP).
`items[].compensationPence`required	`integer`	Integer pence (GBP). Fixed late payment compensation the owner may add (Late Payment of Commercial Debts (Interest) Act 1998 s5A); not added unless they choose to.
`items[].subject`required	`string`
`items[].body`required	`string`
`items[].status`required	`string (ReminderStatus)`	One of: `to_approve`, `sent`, `dismissed`
`items[].draftedOn`required	`string (date)`	example "2026-03-31"
`items[].sentAt`required	`string (date-time)`nullable
`items[].sentTo`required	`string`nullable

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

Edit a reminder before sending it

PATCH/api/v1/books/reminders/{id}

Scopes: books:write
Access: A signed-in Tolvi session only, never an API token.

A person at the business, signed in. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for PATCH /api/v1/books/reminders/{id}
Name	In	Type	Description
`id`required	path	`string (uuid)`

Request body

Required. application/json: object (UpdateSalesReminder).

Request body for PATCH /api/v1/books/reminders/{id}
Field	Type	Description
`subject`required	`string`	up to 200 characters
`body`required	`string`	up to 5000 characters

Responses

200 OK, `application/json`

Body: object (SalesReminder).

A reminder drafted for an overdue (or nearly due) invoice. It goes only when a person at the business presses Send.

200 OK response for PATCH /api/v1/books/reminders/{id}
Field	Type	Description
`id`required	`string (uuid)`
`invoiceId`required	`string (uuid)`
`invoiceNumber`required	`string`
`customerName`required	`string`
`customerEmail`required	`string`nullable
`tone`required	`string (ReminderTone)`	One of: `friendly`, `firm`, `final`
`daysOverdue`required	`integer`	Negative before the due date.
`outstandingPence`required	`integer`	Integer pence (GBP).
`compensationPence`required	`integer`	Integer pence (GBP). Fixed late payment compensation the owner may add (Late Payment of Commercial Debts (Interest) Act 1998 s5A); not added unless they choose to.
`subject`required	`string`
`body`required	`string`
`status`required	`string (ReminderStatus)`	One of: `to_approve`, `sent`, `dismissed`
`draftedOn`required	`string (date)`	example "2026-03-31"
`sentAt`required	`string (date-time)`nullable
`sentTo`required	`string`nullable

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Approve and send a reminder

POST/api/v1/books/reminders/{id}/send

Scopes: books:write
Access: A signed-in Tolvi session only, never an API token.

Emails it to the customer as it stands. Only a person at the business, signed in; 409 if the invoice has been paid. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/reminders/{id}/send
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (SalesReminder).

A reminder drafted for an overdue (or nearly due) invoice. It goes only when a person at the business presses Send.

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Dismiss a reminder

POST/api/v1/books/reminders/{id}/dismiss

Scopes: books:write
Access: A signed-in Tolvi session only, never an API token.

Not sent. The schedule moves on to the next step. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/reminders/{id}/dismiss
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (SalesReminder).

A reminder drafted for an overdue (or nearly due) invoice. It goes only when a person at the business presses Send.

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

List repeating invoices

GET/api/v1/books/recurring-invoices

Scopes: books:read

By default those still running or paused. invoiceId finds the one an invoice was set up from, or made by. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/recurring-invoices
Name	In	Type	Description
`customerId`	query	`string (uuid)`
`invoiceId`	query	`string (uuid)`
`status`	query	`string`	One of: `current`, `active`, `paused`, `stopped`, `all`

Responses

200 OK, `application/json`

Body: object (SalesRecurringInvoiceList).

200 OK response for GET /api/v1/books/recurring-invoices
Field	Type	Description
`items`required	`array of SalesRecurringInvoice`
`items[].id`required	`string (uuid)`
`items[].customerId`required	`string (uuid)`
`items[].customerName`required	`string`
`items[].customerEmail`required	`string`nullable
`items[].sourceDocumentId`required	`string (uuid)`nullable	The invoice it was set up from.
`items[].frequency`required	`string (SalesRepeatFrequency)`	One of: `weekly`, `monthly`, `quarterly`, `yearly`
`items[].frequencyText`required	`string`	example "every month"
`items[].status`required	`string (SalesRepeatStatus)`	active: makes one on nextOn. paused: makes none until resumed. stopped: for good. One of: `active`, `paused`, `stopped`
`items[].nextOn`required	`string (date)`nullable	The next date one is made. Null when paused or stopped. example "2026-03-31"
`items[].firstOn`required	`string (date)`	example "2026-03-31"
`items[].autoSend`required	`boolean`	false (the default): each one is a draft for the owner to check. true: issued and emailed on the day, in the name of the person who turned it on.
`items[].autoSendAt`required	`string (date-time)`nullable
`items[].amountPence`required	`integer`	What each one bills, with VAT, in pence.
`items[].summary`required	`string`	The first line’s description, to recognise it by.
`items[].lineCount`required	`integer`
`items[].runCount`required	`integer`
`items[].lastRunOn`required	`string (date)`nullable	example "2026-03-31"
`items[].lastDocumentId`required	`string (uuid)`nullable	The last invoice made.
`items[].lastProblem`required	`string`nullable	What went wrong on the last run, in plain words.
`items[].createdAt`required	`string (date-time)`

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

Repeat an invoice

POST/api/v1/books/recurring-invoices

Scopes: books:write
Retries: Send an Idempotency-Key to make retries safe.

Copies the invoice’s customer, lines, note and terms. On each date Tolvi makes a new draft for the owner to check: nothing is numbered, posted or sent. 409 if the invoice already repeats. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/recurring-invoices
Name	In	Type	Description
`Idempotency-Key`	header	`string`	A unique key (1-255 visible characters) to make retries safe. Replayed for 24 hours. 1 to 255 characters

Request body

Required. application/json: object (SalesRecurringInvoiceInput).

Request body for POST /api/v1/books/recurring-invoices
Field	Type	Description
`invoiceId`required	`string (uuid)`	The invoice to repeat: its customer, lines, note and terms are copied.
`frequency`required	`string (SalesRepeatFrequency)`	One of: `weekly`, `monthly`, `quarterly`, `yearly`
`firstOn`required	`string (date)`	The first date to make one. Today or later. example "2026-03-31"

Responses

201 Created, `application/json`

Body: object (SalesRecurringInvoice).

A repeating invoice: what it bills, how often, and when the next one is made.

201 Created response for POST /api/v1/books/recurring-invoices
Field	Type	Description
`id`required	`string (uuid)`
`customerId`required	`string (uuid)`
`customerName`required	`string`
`customerEmail`required	`string`nullable
`sourceDocumentId`required	`string (uuid)`nullable	The invoice it was set up from.
`frequency`required	`string (SalesRepeatFrequency)`	One of: `weekly`, `monthly`, `quarterly`, `yearly`
`frequencyText`required	`string`	example "every month"
`status`required	`string (SalesRepeatStatus)`	active: makes one on nextOn. paused: makes none until resumed. stopped: for good. One of: `active`, `paused`, `stopped`
`nextOn`required	`string (date)`nullable	The next date one is made. Null when paused or stopped. example "2026-03-31"
`firstOn`required	`string (date)`	example "2026-03-31"
`autoSend`required	`boolean`	false (the default): each one is a draft for the owner to check. true: issued and emailed on the day, in the name of the person who turned it on.
`autoSendAt`required	`string (date-time)`nullable
`amountPence`required	`integer`	What each one bills, with VAT, in pence.
`summary`required	`string`	The first line’s description, to recognise it by.
`lineCount`required	`integer`
`runCount`required	`integer`
`lastRunOn`required	`string (date)`nullable	example "2026-03-31"
`lastDocumentId`required	`string (uuid)`nullable	The last invoice made.
`lastProblem`required	`string`nullable	What went wrong on the last run, in plain words.
`createdAt`required	`string (date-time)`

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 409 Conflict, 422 Unprocessable content, 429 Too many requests, as problem details (application/problem+json).

Get a repeating invoice

GET/api/v1/books/recurring-invoices/{id}

Scopes: books:read

Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for GET /api/v1/books/recurring-invoices/{id}
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (SalesRecurringInvoice).

A repeating invoice: what it bills, how often, and when the next one is made.

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Change a repeating invoice

PATCH/api/v1/books/recurring-invoices/{id}

Scopes: books:write

How often, the next date (later dates follow from it), or what it bills, copied from another invoice for the same customer. Invoices already made don’t change. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for PATCH /api/v1/books/recurring-invoices/{id}
Name	In	Type	Description
`id`required	path	`string (uuid)`

Request body

Required. application/json: object (SalesRecurringInvoicePatch).

Request body for PATCH /api/v1/books/recurring-invoices/{id}
Field	Type	Description
`frequency`	`string (SalesRepeatFrequency)`	One of: `weekly`, `monthly`, `quarterly`, `yearly`
`nextOn`	`string (date)`	The next date to make one. Today or later; later dates follow from it. example "2026-03-31"
`fromInvoiceId`	`string (uuid)`	Bill what this invoice bills from now on: its lines, note and terms (same customer).

Responses

200 OK, `application/json`

Body: object (SalesRecurringInvoice).

A repeating invoice: what it bills, how often, and when the next one is made.

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Turn automatic sending on or off

POST/api/v1/books/recurring-invoices/{id}/auto-send

Scopes: books:write
Access: A signed-in Tolvi session only, never an API token.

On: each invoice is issued and emailed on its date, without anyone checking it, in the name of the person who turned this on. Only a person at the business, signed in: never an accountant in the books, an API client or an assistant. If anything is in the way the invoice stays a draft, and the schedule says why. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/recurring-invoices/{id}/auto-send
Name	In	Type	Description
`id`required	path	`string (uuid)`

Request body

Required. application/json: object (SalesRecurringAutoSend).

Request body for POST /api/v1/books/recurring-invoices/{id}/auto-send
Field	Type	Description
`on`required	`boolean`	true: issue and email each one on the day. false: each one is a draft to check.

Responses

200 OK, `application/json`

Body: object (SalesRecurringInvoice).

A repeating invoice: what it bills, how often, and when the next one is made.

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Pause a repeating invoice

POST/api/v1/books/recurring-invoices/{id}/pause

Scopes: books:write

No more are made until it is resumed. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/recurring-invoices/{id}/pause
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (SalesRecurringInvoice).

A repeating invoice: what it bills, how often, and when the next one is made.

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Resume a paused repeating invoice

POST/api/v1/books/recurring-invoices/{id}/resume

Scopes: books:write

From its next date on or after today. Dates missed while it was paused aren’t billed. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/recurring-invoices/{id}/resume
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (SalesRecurringInvoice).

A repeating invoice: what it bills, how often, and when the next one is made.

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Stop a repeating invoice

POST/api/v1/books/recurring-invoices/{id}/stop

Scopes: books:write

For good. Invoices already made stay as they are. Part of the books product: the firm must have it and you must have access to it.

Parameters

Parameters for POST /api/v1/books/recurring-invoices/{id}/stop
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (SalesRecurringInvoice).

A repeating invoice: what it bills, how often, and when the next one is made.

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Books: sales

Who owes the business money

Responses

200 OK, application/json

Get the invoice settings

Responses

200 OK, application/json

Change the invoice settings

Request body

Responses

200 OK, application/json

Get a short-lived link to the logo

Responses

200 OK, application/json

Start uploading a logo

Request body

Responses

200 OK, application/json

Take the logo off invoices

Responses

200 OK, application/json

Finish uploading a logo

Responses

200 OK, application/json

Get a customer’s statement

Parameters

Responses

200 OK, application/json

Get a customer’s statement as a PDF

Parameters

Responses

200 OK, application/pdf

Email a customer their statement

Parameters

Request body

Responses

200 OK, application/json

List customers

Parameters

Responses

200 OK, application/json

Add a customer

Parameters

Request body

Responses

201 Created, application/json

Get a customer

Parameters

Responses

200 OK, application/json

Change a customer

Parameters

Request body

Responses

200 OK, application/json

Archive a customer

Parameters

Responses

200 OK, application/json

Restore an archived customer

Parameters

Responses

200 OK, application/json

List invoices or credit notes

Parameters

Responses

200 OK, application/json

Start a draft invoice

Parameters

Request body

Responses

201 Created, application/json

Draft an invoice from a sentence (Tolvi AI)

Request body

Responses

200 OK, application/json

Get an invoice or credit note

Parameters

Responses

200 OK, application/json

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/pdf`

200 OK, `application/json`

200 OK, `application/json`

201 Created, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

201 Created, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

201 Created, `application/json`

200 OK, `application/json`

201 Created, `application/json`

200 OK, `application/json`

201 Created, `application/json`

200 OK, `application/pdf`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

200 OK, `application/json`

201 Created, `application/json`