API Reference

Invoices

Invoices, estimates, and credit memos share the same routes, distinguished by invoiceType. Every invoice object includes a derived status field (draft, approved, sent, unpaid, partial, paid, overdue, void) alongside the raw isDraft / approved / isSent / paymentStatus flags. All references use UUIDs.

Last updated 2026-11-18

Some fields work differently in US and NZ workspaces

Showing US sales tax and NZ GST rules.

Overview

The Invoices API lets your integration create, list, update, approve, send, and delete invoices, estimates, and credit memos in a workspace. All document types share the same `/partners/invoices` routes and are distinguished by `invoiceType` (`invoice`, `estimate`, or `memo`).

Every invoice-shaped object includes a derived `status` field (for example draft, approved, sent, unpaid, partial, paid, overdue, void) computed from `isDraft`, `approved`, `isSent`, and `paymentStatus`. Partner responses expose UUIDs as `id` and strip internal numeric foreign keys. For migrations you may pass inline `customer` or per-line `product` objects instead of UUIDs, or set `isDraft: false` to post revenue journals in one step.

Key concepts

Document types

Set `invoiceType` to `invoice` (default), `estimate`, or `memo` (credit memo). Credit memos cannot be recurring — use Recurring Invoice Templates for scheduled invoices only.

Derived status

Partner responses include a computed `status` alongside raw flags. After send, an open unpaid invoice may surface as `sent` rather than `unpaid`. See the backend `computePartnerInvoiceStatus` helper for the full mapping.

Line item taxes

On create, `unitPrice` is copied to `price` when omitted. A line's tax codes go in `taxes` (tax UUIDs from List tax codes); omit it to take the product's codes. `nonTaxable` behaves differently in US and NZ workspaces — see the US and NZ cards.

US· Sales taxLine taxes

Each line charges the sales tax codes in its `taxes` array, or the product's codes when `taxes` is omitted. `nonTaxable: true` keeps the code but charges no tax, so the sale reports as Non-Taxable under that code. A tax-exempt customer's taxed lines are raised Non-Taxable unless the line sends `customerExemptionOverridden: true`.

NZ· GSTLine GST codes

Each line carries a GST code in `taxes`: `15% GST on Income` (standard-rated), `Zero Rated` (counted in GST return boxes 5 and 6), or `No GST` (left off the GST return). Zero Rated and No GST are both 0% but are different codes. Pick them by UUID from List tax codes. `nonTaxable: true` and `taxes: []` both raise the line with no code at all, which is never a zero-rated supply.

Foreign-currency rate

A document in another currency is booked at the spot rate for its date, from Open Exchange Rates unless the workspace has its own rate for that currency. To use your rate instead, send `bookingExchangeRate` with `exchangeRateSource: "user"`. The document keeps its face amounts in its own currency; responses also carry `bookingExchangeRate`, `exchangeRateDate`, `exchangeRateSource` (`OXR`, `user`, `bank` or `date_override`) and `baseTotal`, the total in the workspace currency.

Revaluation and currency gains

COUNT revalues open foreign-currency AR, AP and foreign-currency accounts at the closing rate at each month end, posting to Unrealised Currency Gain/Loss and reversing on the first day of the next month. When a payment settles a foreign document at a different rate, the difference posts to Realised Currency Gain/Loss. Both accounts are created automatically, so there is nothing to post yourself.

Free-text lines

A line with no `productUuid` is a free-text line — the app's "Custom" line. It needs `categoryAccountUuid` (the income account it posts to), carries its item name in `name` and any detail in `description`, and takes only the taxes it names. Product lines may also send `categoryAccountUuid` to post to a different income account than the product's own. Unrecognized line fields are ignored and reported in `_partnerWarnings`.

Lifecycle and allowed operations

Typical flow: create (draft) → approve → send → pay via assign-to-bills-invoices. update/delete work on drafts only; send requires approval; there is no revert-to-draft API — use credit memos to correct approved invoices.

Credit application

Apply credit memos to invoices with the apply-multiple-credit and apply-credit-to-multiple-invoices routes. All IDs in those bodies are partner invoice UUIDs (the `id` field on invoice/memo objects).

The invoice object

Core fields returned on invoice, estimate, and credit memo records.

Attributes

iduuid

Document identifier (UUID). Use in path parameters.

invoiceNumberstring

Human-readable document number.

invoiceTypeenum

Document type.

One of: invoice, estimate, memo

customerUuiduuid

UUID of the customer this document belongs to.

datedate

Document date (ISO).

dueDatedate

Due date (ISO), when applicable.

currencystring

ISO 4217 currency code.

statusstring

Derived lifecycle status (draft, approved, sent, unpaid, partial, paid, overdue, void, etc.).

isDraftboolean

Whether the document is still a draft.

approvedboolean

Whether the document has been approved.

isSentboolean

Whether the document has been emailed to the customer.

paymentStatusstring

Raw payment status (unpaid, partial, paid, etc.).

subtotalnumber

Subtotal before tax.

taxTotalnumber

Total tax amount.

totalnumber

Grand total including tax.

amountDuenumber

Outstanding balance.

productsarray

Products or services billed on this document.

createdAtdatetime

ISO 8601 creation timestamp.

updatedAtdatetime

ISO 8601 last update timestamp.

Example
{
  "id": "f6a7b8c9-d0e1-2345-fabc-456789012345",
  "invoiceNumber": "INV-1042",
  "invoiceType": "invoice",
  "customerUuid": "dfa3219e-6af8-4c53-997a-037534f63a35",
  "date": "2026-03-01",
  "dueDate": "2026-03-31",
  "currency": "USD",
  "status": "sent",
  "isDraft": false,
  "approved": true,
  "isSent": true,
  "paymentStatus": "unpaid",
  "subtotal": 1000,
  "taxTotal": 85,
  "total": 1085,
  "amountDue": 1085,
  "products": [
    {
      "productUuid": "aa11bb22-cc33-dd44-ee55-ff6677889900",
      "description": "Consulting services",
      "quantity": 10,
      "unitPrice": 100,
      "nonTaxable": false
    }
  ],
  "createdAt": "2026-03-01T09:00:00.000Z",
  "updatedAt": "2026-03-02T11:15:00.000Z"
}

Credit memos share these routes

Credit memos use the same endpoints with `invoiceType: "memo"`. See the Credit Memos API reference for memo-focused examples.

Non-draft edits are restricted

Updates to approved or sent invoices are field-specific. Many invalid changes return 400. Concurrent updates may fail with a lock error.

Three ways to send a file

JSON `attachments` entries take a public `url` (COUNT downloads and keeps a copy) or the file inline as `contentBase64` (up to 10 MB). The `/upload` routes take `multipart/form-data`. All three are held to the same per-file cap and file types, at most 10 files a request, and every file is virus-scanned before anything is saved. To read a file back without following a link, call the attachment's `/content` route, which returns it base64-encoded.

File links are signed per response

Any `documentUrl`, `receiptUrl`, `pdfUrl` or `bankStatementUrl` on COUNT storage comes back as a short-lived signed link, minted only after COUNT proves the file belongs to this workspace. Use it straight away and call again for a fresh one; do not store it. A file COUNT cannot prove is the workspace's comes back as `null`. A link you attached to an outside file is returned exactly as you sent it.

Recent changes

2026-11-18

Incremental sync: updatedSince on every list endpoint, includeDeleted, and the deleted-records feed

Every Partner API list endpoint now takes updatedSince, so an integration can pull only what changed instead of re-reading whole lists. Pass an ISO 8601 date-time and the list returns the records created or changed at or after it, oldest change first, with nextUpdatedSince and hasMore beside the rows; pass nextUpdatedSince back as updatedSince to read the next page, and keep it for the next poll once hasMore is false. Paging by cursor means a record changed mid-walk can no longer move between pages and be skipped, so updatedSince cannot be combined with page above 1 or a sort. includeDeleted=true returns deleted records with isDeleted: true on vendors, customers, products, people, taxes, projects, project tasks, tasks, time entries, recurring invoice templates, the chart of accounts, transactions, invoices, and bills. The chart of accounts returns a flat list of changed accounts in this mode, each naming its parent in parentAccountUuid. Records removed outright — tags, tag groups, journal entry lines, expense receipts, customer contacts, addresses and notes, budgets, and any other hard delete — are listed by the new GET /partners/deleted-records, which keeps 90 days. updatedFrom and updatedTo stay on transactions, invoices, and bills, now read as UTC when they carry no offset. The new Keeping in Sync guide (/guides/keeping-in-sync) puts the pieces together into a 15-minute poll with a sync-now button. The MCP catalog adds COUNT_list_deleted_records, and every list tool takes updatedSince (and includeDeleted where it applies) under query.

2026-11-18

Line tags, foreign-currency rates, transfers and journal balance checks

Documented behaviour the reference was missing or had wrong. Bill lines take their own tags in `lineItems[].tagUuids`, which code that line's expense and tax postings, and manual journal lines take `lines[].tagUuids`; invoices take `tagUuids` for the whole document, on create and update. Bills and invoices in another currency are booked at the spot rate for their date, and `bookingExchangeRate` with `exchangeRateSource: "user"` sets your own rate; COUNT revalues open foreign AR, AP and accounts at each month end and posts realised gains and losses on payment. A transfer is a transaction categorized to another bank, cash, credit card or loan account, and change-category takes `linkedTransferTransactionUuid` to pair it with an existing row; bulk category change rejects those accounts. Journal entry create accepts unbalanced postings, while update requires debits to equal credits; the reference previously said create rejected them.

2026-11-18

Line taxes on invoices and bills, split by US and NZ

Documented the line tax fields the reference was missing and how each behaves in US and NZ workspaces. Bill lines take one tax code in `lineItems[].taxUuid` (NZ: the GST code; US: ignored, bills carry no tax), and bill responses show it as `appliedTax`. Invoice, credit memo and recurring template lines take tax code UUIDs in `taxes`, the document takes `productsPriceType` (`tax-exclusive` or `tax-inclusive`), and `nonTaxable` and `customerExemptionOverridden` now say what they do in each country: in the US a Non-Taxable line keeps its code, in NZ it is cleared. The Taxes page lists the five NZ GST codes, where each reports on the GST return (Zero Rated in boxes 5 and 6, No GST nowhere), and which accounts each fits. Customer `taxExcluded` is a tax exemption, not tax-exclusive pricing, and customer and account `taxes` take tax UUIDs. A US / NZ switch in the header, and on every page with country-specific rules, shows one country's notes at a time; links can open in either view with `?region=us` or `?region=nz`.

2026-11-18Breaking

Every attachment in COUNT through the API and MCP

Attachments can now be listed, added, read back and removed through the Partner API on bills, invoices, recurring invoice templates, transaction receipts, manual journal entries, tasks, expense receipts, Documents and reconciliation bank statements. Each record type gains an `attachments` (or `receipts` / `bank-statement`) route that takes JSON entries, either `{ url }` (COUNT downloads and keeps its own copy) or `{ fileName, contentBase64, contentType? }`, plus an `/upload` route for multipart files. Files are capped per route (5 MB for invoices, templates, transaction receipts and Documents, 10 MB for expense receipts, 20 MB for bills, journal entries and tasks, 25 MB for bank statements), at most 10 per request, virus-scanned, and saved together or not at all. A new `/content` route on each returns one file base64-encoded (up to 10 MB), and GET /partners/documents/{uuid}/download-links returns signed view and download links. Breaking: `documentUrl`, `receiptUrl`, `pdfUrl` and `bankStatementUrl` in responses are now short-lived signed links, and `null` when COUNT cannot prove the file is the workspace's. POST /partners/invoices/{uuid}/attachments now stores a copy of each file and answers 201 with `data.attachments` instead of 200 with `data.invoice`. Invoice upload responses no longer include internal ids (`invoiceId`, `defaultInvoiceAttachmentId`, `recurringInvoiceTemplateId`, `uploadedBy`). Bill create and update accept inline content in `attachments`, and an empty list adds nothing. Attachment adds and content reads are limited to 40 a minute per client and workspace. The MCP catalog adds 35 tools, including a Documents category, and content tools deliver the file as an embedded resource rather than as text.

2026-10-03

Bill submit and refunds, reconciliation drafts, report filters, 30 MCP tools, and the Claude plugin

Documented the five partner routes the reference was missing: POST /partners/bills/{uuid}/submit, POST /partners/bills/{uuid}/assign-transaction (pay a bill, or refund a vendor memo with an income transaction), PATCH /partners/invoices/{uuid}/add-transactions (including credit memo refunds), and PATCH and DELETE /partners/reconciliations/{uuid} for correcting or discarding a draft. The account transactions report gains a reference-number range (checkNumberFrom/checkNumberTo) and the unknown-counterparty drill-down (unknownCustomerAr/unknownVendorAp), both accrual-only. Invoice and credit memo lines accept free-text Custom lines with categoryAccountUuid and name. Corrected the reference where it disagreed with the backend: dueDate is required on invoices and estimates, bills move through submitted and rejected as well as draft and approved, and a bill does have its own assign-transaction route. npm run check:parity now reports 178 documented routes against 178 backend routes. The MCP catalog adds 30 tools — customer contacts, addresses, notes, merge and revenue overview, GST settings, bill submit and memo refunds, reconciliation draft update/delete, COUNT_find_tool, COUNT_report_problem, and saved AI skills — moving the advertised count from 180 to 210. New pages cover the COUNT Claude plugin (/tools/claude-plugin) and the MCP brain, workspace memory and problem reports (/guides/mcp-brain-and-memory), and the FAQ gains the connector and API topics COUNT_knowledge serves to agents.

2026-09-22

Customer sub-resources, merge, GST settings, and the last bulk routes

Closed every remaining gap between the reference and the backend partner routes — 20 endpoints that existed in count-dev but had no documentation. Customers gained its sub-resources: contacts, addresses, and notes each get full list/create/update/delete coverage, plus GET /partners/customers/{uuid}/revenue-overview and the two-step merge flow (POST /partners/customers/merge/preview, then POST /partners/customers/merge), which repoints every record onto a target customer and cannot be undone through the API. Workspace gained GET and PATCH /partners/workspace/gst-settings, including the manage_settings permission the PATCH requires and the 409 that locks the accounting basis after a return is filed. Also documented GET /partners/invoices/generate/number, POST /partners/projects/bulk, and POST /partners/transactions/review-bulk. npm run check:parity now reports 173 documented routes against 173 backend routes.

2026-09-07

Accounting Playbooks and Ledger Semantics published as documentation

The workflows and behaviour rules the MCP server serves to agents through COUNT_playbooks and COUNT_knowledge are now readable documentation. Accounting Playbooks (/guides/playbooks) covers nine ordered workflows across 54 steps — invoicing, credit memos, recurring templates, vendor bill payment, chart-of-accounts setup, migration imports, budget planning and round-trip, and month-end review — each naming the exact tool per step. Ledger Semantics & Lifecycles (/guides/ledger-semantics) documents 33 confirmed behaviours across twelve resources: the state each operation is valid in, the fields accepted and then ignored, and the calls that cannot be undone, with every irreversible behaviour collected in one table at the top of the page. Both pages carry the COUNT_playbooks and COUNT_knowledge ids they were ported from so the agent-facing and human-facing copies stay in step. Playbooks, lifecycle sections, and individual behaviour rules are indexed into site search.

2026-07-28

Connections, reconciliations, opening balance, workspace cutover, and transaction bulk ops

Documented Partner API groups for bank Connections (including Plaid Hosted Link connect/complete/reconnect), Reconciliations (create draft + complete), Opening Balance (get/set conversion balance), and Workspace (PATCH cutoverDate). Added PATCH /partners/transactions/change-category-bulk and exclude-bulk. Removed non-existent POST /partners/bills/bulk and /partners/invoices/bulk from the reference. Extended the MCP tool catalog with the matching COUNT_* tools plus remote-only COUNT_get_bulk_task_status and COUNT_remember/recall/forget.

2026-06-29

Budgets API and documentation parity

Added the Budgets API reference (14 endpoints), invoice send-history, and account sub-types list. Introduced an automated parity check (`npm run check:parity`) that compares documented routes against count-dev. Normalized customer path parameters to `{uuid}` and fixed the documents chunk-upload progress path.

2026-06-21

Complete Partner API reference

Documented all remaining API reference groups: Chart of Accounts, Vendors, Products & Services, Recurring Invoice Templates, Credit Memos, Bills, Journal Entries, Tags, People, Projects, Tasks, Time Entries, Expense Receipts, Reports, and Workspace Stats. Added missing invoice endpoints (audit log, attachments, credit application, remove transaction) and group overviews for Invoices and Transactions.

Endpoints

GET
List invoices/partners/invoices

Returns a paginated list of invoices, estimates, or credit memos.

GET
Get an invoice/partners/invoices/{uuid}

Retrieves a single invoice, estimate, or credit memo by its UUID.

GET
Get the next invoice number/partners/invoices/generate/number

Returns the number COUNT would assign to the next invoice, estimate, or credit memo.

POST
Create an invoice/partners/invoices

Creates an invoice, estimate, or credit memo (invoiceType: "memo").

PATCH
Update an invoice/partners/invoices/{uuid}

Updates an invoice. Edits to non-draft invoices are field-specific and may be rejected.

PATCH
Approve an invoice/partners/invoices/{uuid}/approve

Approves a draft invoice or credit memo.

POST
Send an invoice/partners/invoices/{uuid}/send

Emails the invoice to the customer. Requires a non-draft invoice with a customer and products.

GET
Get the public link/partners/invoices/{uuid}/public-link

Returns a shareable public link for the invoice, creating the public token if needed.

GET
Get audit log/partners/invoices/{uuid}/audit-log

Returns the audit history for an invoice, estimate, or credit memo.

GET
Get send history/partners/invoices/{uuid}/send-history

Returns email send history and public-view analytics for an invoice, estimate, or credit memo.

GET
List invoice attachments/partners/invoices/{uuid}/attachments

Lists the files attached to an invoice, estimate or credit memo.

POST
Add attachments/partners/invoices/{uuid}/attachments

Attaches files to an invoice from public URLs or inline base64 content.

POST
Upload attachment/partners/invoices/{uuid}/attachments/upload

Uploads one file attachment via multipart form data.

PATCH
Rename invoice attachment/partners/invoices/{uuid}/attachments/{attachmentUuid}

Changes the display title of one invoice attachment.

DELETE
Delete invoice attachment/partners/invoices/{uuid}/attachments/{attachmentUuid}

Removes one file from an invoice.

GET
Get invoice attachment content/partners/invoices/{uuid}/attachments/{attachmentUuid}/content

Returns one invoice attachment's file, base64-encoded.

PATCH
Apply multiple credits to invoice/partners/invoices/{uuid}/apply-multiple-credit-to-invoice

Applies one or more credit memos to the target invoice.

PATCH
Apply credit to multiple invoices/partners/invoices/{uuid}/apply-credit-to-multiple-invoices

Applies a credit memo to one or more target invoices.

PATCH
Remove credit/partners/invoices/{uuid}/remove-credit

Unapplies a credit memo from an invoice.

PATCH
Add payment transactions/partners/invoices/{uuid}/add-transactions

Settles whole transactions against an invoice, or records a refund paid out on a credit memo.

PATCH
Remove transaction/partners/invoices/{uuid}/remove-transaction

Unassigns a payment transaction from an invoice.

DELETE
Delete an invoice/partners/invoices/{uuid}

Deletes an invoice, estimate, or credit memo.