API Reference
Bills
Bills are vendor payables — amounts your workspace owes to suppliers. Partner routes cover listing, creating, updating, approving, and deleting bills, applying vendor memos, and removing transaction payments. All references use UUIDs.
Last updated 2026-11-19
Some fields work differently in US and NZ workspaces
Showing US sales tax and NZ GST rules.
Overview
The Bills API lets your integration manage accounts-payable documents in a workspace. A bill records what you owe a vendor, its line-item expenses, approval state, and payment status. Vendor memos (`billType: "vendor_memo"`) are also returned through the same routes and can be applied toward open bills.
Every bill is identified by a UUID returned as `id`. Use UUID fields in request bodies — `vendorUuid`, `categoryAccountUuid` on line items, `tagUuids`, and `projectUuid` — not internal numeric ids. For migrations you may pass inline `vendor: { name, email? }` instead of `vendorUuid`, or set `approvalStatus: approved` to post historical A/P journals in one step. Bills default to draft; call approve when you create as draft.
Key concepts
UUID-only payloads
Create and update bodies accept `vendorUuid`, `lineItems[].categoryAccountUuid`, optional `lineItems[].projectUuid`, `customerUuid` and `taxUuid`, `tagUuids`, and `projectUuid`. Numeric `vendorId`, `categoryAccountId`, and `tags` are rejected, and a numeric line `taxId` is ignored. A line's `fixedAssetAssignment` takes `fixedAssetUuid` / `fixedAssetTypeUuid`; numeric `fixedAssetId` / `fixedAssetTypeId` are rejected.
US· Sales taxBills carry no sales tax
Bills carry no sales tax. `lineItems[].taxUuid` is ignored and the bill's tax total is 0, so enter each line at the amount you paid the vendor.
NZ· GSTLine GST codes
Each line takes one GST code in `lineItems[].taxUuid`, a UUID from List tax codes; null clears it. By default `price` excludes GST and the GST is added on top. Use `15% GST on Expenses` for a purchase that carries GST, `No GST` for one that does not (left off the GST return), or `GST on Imports` on the GST on Imports account only, where the whole line amount is the GST. An Expenses account refuses sales-side codes (`15% GST on Income`, `Zero Rated`) with 400.
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.
Draft → approved → paid
New bills start as draft (`approvalStatus: draft`). POST /{uuid}/submit moves a draft or rejected bill to `submitted` and posts its accrual journal. POST /{uuid}/approve makes the bill eligible for payment; a caller who is not a workspace owner or admin must submit first. Pay with POST /partners/transactions/{uuid}/assign-to-bills-invoices, POST /{uuid}/assign-transaction, or by applying vendor memos.
Lifecycle and allowed operations
Typical flow: create (draft) → submit → approve → pay via assign-to-bills-invoices, assign-transaction, or vendor memos. update/delete work on drafts only; there is no revert-to-draft API.
Vendor memos
Create a vendor memo with `billType: "vendor_memo"` on POST /partners/bills, and list them with GET /partners/bills?billType=vendor_memo. Apply one to an approved bill with POST /{uuid}/apply-vendor-memos (same vendor, sufficient balance) and remove it again with POST /{uuid}/unassign-vendor-memos, or record a refund received from the vendor with POST /{memoUuid}/assign-transaction and Income transactions.
Payment with transactions
Use the Transactions API assign-to-bills-invoices route with matchingType bill and an Expense transaction; paymentAmount must not exceed amountDue and must match bill currency. POST /{uuid}/assign-transaction settles whole transactions against a workspace-currency bill instead.
Deletion rules
Draft bills can be soft-deleted. Bills with paidAmount > 0 cannot be deleted until payments are unassigned.
The bill object
Core fields on a bill or vendor memo. Detail responses embed line items, vendor, payments (`transactions`), and applied vendor memos.
Attributes
iduuidBill identifier (UUID). Use in path parameters.
billNumberstringHuman-readable bill number.
billTypeenumDocument type. Vendor memos are credits from the vendor.
One of: bill, vendor_memo
datedateBill date (ISO).
dueDatedatePayment due date (ISO).
currencystringISO 4217 currency code.
approvalStatusenumApproval workflow state. Only `draft` bills stay unposted; `submitted` and `approved` bills carry their accrual journal.
One of: draft, submitted, approved, rejected
statusstringCombined approval and payment status (for example draft, unpaid, paid, overdue).
totalnumberBill total including tax.
paidAmountnumberAmount already paid or applied.
amountDuenumberOutstanding balance.
notesstringFree-text notes.
purchaseOrderNumberstringOptional PO reference.
isDeletedbooleanSoft-delete flag. GET by UUID may still return deleted rows — filter client-side when needed.
vendorobjectLinked vendor record, including address when present.
lineItemsarrayExpense lines on the bill.
descriptionstringLine description.
quantitynumberQuantity.
pricenumberUnit price.
totalnumberLine total.
categoryAccountUuiduuidExpense or category account UUID.
projectUuiduuidOptional project UUID on the line.
customerUuiduuidOptional customer UUID for billable expenses.
appliedTaxobjectThe line's tax code, or null.
- US· Sales taxAlways null; bills carry no tax.
- NZ· GSTThe line's GST code.
taxNamestringName of the line's tax code when it was applied, or null.
taxPercentagenumberRate applied to the line.
taxnumberTax amount on the line.
- US· Sales taxAlways 0.
- NZ· GSTThe GST on the line.
transactionsarrayExpense transactions applied as payment.
appliedVendorMemosarrayVendor memos applied toward this bill.
createdAtdatetimeISO 8601 creation timestamp.
updatedAtdatetimeISO 8601 last update timestamp.
{
"id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"billNumber": "BILL-1042",
"billType": "bill",
"date": "2026-01-15",
"dueDate": "2026-02-15",
"currency": "USD",
"approvalStatus": "approved",
"status": "unpaid",
"total": 250,
"paidAmount": 0,
"amountDue": 250,
"notes": "Office supplies for Q1",
"purchaseOrderNumber": null,
"isDeleted": false,
"vendor": {
"id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
"name": "Office Depot",
"email": "ap@officedepot.example"
},
"lineItems": [
{
"id": "a4b5c6d7-e8f9-0123-abcd-456789012345",
"description": "Office supplies",
"quantity": 1,
"price": 250,
"total": 250,
"categoryAccountUuid": "c3d4e5f6-a7b8-9012-cdef-123456789012"
}
],
"transactions": [],
"appliedVendorMemos": [],
"tagUuids": [],
"createdAt": "2026-01-15T10:30:00.000Z",
"updatedAt": "2026-01-28T14:22:30.000Z"
}Choosing a payment route
POST /partners/transactions/{transactionId}/assign-to-bills-invoices (matchingType bill) takes a partial paymentAmount and is the only route for foreign-currency bills. POST /partners/bills/{uuid}/assign-transaction settles whole transactions against a workspace-currency bill, and records refunds on vendor memos. MCP equivalents: COUNT_assign_transaction_to_bills_invoices, COUNT_submit_bill, and COUNT_record_vendor_memo_refund.Approved bill edits are restricted
PATCH may return 400 when changing dates or line items on approved or paid bills. For structural changes after approval, delete and recreate when deletion rules allow.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.Filter by vendor
Pass comma-separated vendor UUIDs in vendorUuids (from the Vendors API). Do not pass numeric vendors.Related
Recent changes
Fixed assets
The asset register is on the Partner API and MCP. /partners/fixed-asset-types lists, gets, creates, updates and deletes asset types (each with its cost, accumulated depreciation and depreciation expense accounts and default depreciation settings). /partners/fixed-assets lists the register (status, type, search, sort, paging), gets one asset with its posted depreciation, updates and deletes drafts, merges two drafts (POST /merge-drafts) and projects depreciation (GET /{uuid}/projected-depreciation-schedule). POST /{uuid}/register, /unregister and /dispose run the lifecycle; a disposal posts its catch-up depreciation and journal together and refuses a sale missing the account its outcome needs. GET and POST /{uuid}/journal-links and DELETE /{uuid}/journal-links/{linkUuid} manage the journal lines behind an asset's cost, GET /{uuid}/audit-log returns its history, and /{uuid}/attachments lists, adds (multipart or URL) and deletes its files. GET /partners/fixed-asset-depreciation-rates returns the country's reference rates. POST /partners/reports/depreciation-schedule, /asset-register and /fixed-asset-reconciliation generate the fixed asset reports. Bill lines and transaction category changes accept `fixedAssetAssignment` with `fixedAssetUuid` / `fixedAssetTypeUuid`. These routes need the new `fixed-assets` scope (a bare `read` / `write` grant includes it; the reports need `reports:read`) plus View Fixed Assets to read and Administer Fixed Assets to change. The same routes work on client workspaces under /firm-partners/workspace. The MCP catalog adds 22 fixed asset tools and 3 report tools.
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.
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.
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`.
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.
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.
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.
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.
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
/partners/billsReturns a paginated list of bills and vendor memos in the workspace.
/partners/bills/{uuid}Retrieves a single bill by its UUID.
/partners/billsCreates a new vendor bill (draft by default, or approved for migrations).
/partners/bills/{uuid}Updates a bill. Only the fields you send are changed.
/partners/bills/{uuid}Soft-deletes a draft bill.
/partners/bills/{uuid}/submitSubmits a draft or rejected bill for approval and posts its accrual journal.
/partners/bills/{uuid}/approveApproves a draft bill and posts journal entries.
/partners/bills/{uuid}/apply-vendor-memosApplies one or more vendor credit memos toward an approved bill.
/partners/bills/{uuid}/unassign-vendor-memosRemoves a vendor credit memo previously applied to a bill.
/partners/bills/{uuid}/assign-transactionSettles one or more whole transactions against an approved bill or vendor memo.
/partners/bills/{uuid}/unassign-transactionRemoves a previously applied expense transaction payment from a bill.
/partners/bills/{uuid}/attachmentsLists the files attached to a bill or vendor memo.
/partners/bills/{uuid}/attachmentsAdds files to a bill from public URLs or inline base64 content.
/partners/bills/{uuid}/attachments/uploadUploads files to a bill via multipart form data.
/partners/bills/{uuid}/attachments/{attachmentUuid}Changes the display title of one bill attachment.
/partners/bills/{uuid}/attachments/{attachmentUuid}Removes one file from a bill.
/partners/bills/{uuid}/attachments/{attachmentUuid}/contentReturns one bill attachment's file, base64-encoded.
