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

iduuid

Bill identifier (UUID). Use in path parameters.

billNumberstring

Human-readable bill number.

billTypeenum

Document type. Vendor memos are credits from the vendor.

One of: bill, vendor_memo

datedate

Bill date (ISO).

dueDatedate

Payment due date (ISO).

currencystring

ISO 4217 currency code.

approvalStatusenum

Approval workflow state. Only `draft` bills stay unposted; `submitted` and `approved` bills carry their accrual journal.

One of: draft, submitted, approved, rejected

statusstring

Combined approval and payment status (for example draft, unpaid, paid, overdue).

totalnumber

Bill total including tax.

paidAmountnumber

Amount already paid or applied.

amountDuenumber

Outstanding balance.

notesstring

Free-text notes.

purchaseOrderNumberstring

Optional PO reference.

isDeletedboolean

Soft-delete flag. GET by UUID may still return deleted rows — filter client-side when needed.

vendorobject

Linked vendor record, including address when present.

lineItemsarray

Expense lines on the bill.

descriptionstring

Line description.

quantitynumber

Quantity.

pricenumber

Unit price.

totalnumber

Line total.

categoryAccountUuiduuid

Expense or category account UUID.

projectUuiduuid

Optional project UUID on the line.

customerUuiduuid

Optional customer UUID for billable expenses.

appliedTaxobject

The line's tax code, or null.

  • US· Sales taxAlways null; bills carry no tax.
  • NZ· GSTThe line's GST code.
taxNamestring

Name of the line's tax code when it was applied, or null.

taxPercentagenumber

Rate applied to the line.

taxnumber

Tax amount on the line.

  • US· Sales taxAlways 0.
  • NZ· GSTThe GST on the line.
transactionsarray

Expense transactions applied as payment.

appliedVendorMemosarray

Vendor memos applied toward this bill.

createdAtdatetime

ISO 8601 creation timestamp.

updatedAtdatetime

ISO 8601 last update timestamp.

Example
{
  "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.

Recent changes

2026-11-19

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.

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-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-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 bills/partners/bills

Returns a paginated list of bills and vendor memos in the workspace.

GET
Get a bill/partners/bills/{uuid}

Retrieves a single bill by its UUID.

POST
Create a bill/partners/bills

Creates a new vendor bill (draft by default, or approved for migrations).

PATCH
Update a bill/partners/bills/{uuid}

Updates a bill. Only the fields you send are changed.

DELETE
Delete a bill/partners/bills/{uuid}

Soft-deletes a draft bill.

POST
Submit a bill/partners/bills/{uuid}/submit

Submits a draft or rejected bill for approval and posts its accrual journal.

POST
Approve a bill/partners/bills/{uuid}/approve

Approves a draft bill and posts journal entries.

POST
Apply vendor memos to a bill/partners/bills/{uuid}/apply-vendor-memos

Applies one or more vendor credit memos toward an approved bill.

POST
Unassign a vendor memo from a bill/partners/bills/{uuid}/unassign-vendor-memos

Removes a vendor credit memo previously applied to a bill.

POST
Assign transactions as payment/partners/bills/{uuid}/assign-transaction

Settles one or more whole transactions against an approved bill or vendor memo.

POST
Unassign a transaction payment/partners/bills/{uuid}/unassign-transaction

Removes a previously applied expense transaction payment from a bill.

GET
List bill attachments/partners/bills/{uuid}/attachments

Lists the files attached to a bill or vendor memo.

POST
Add bill attachments/partners/bills/{uuid}/attachments

Adds files to a bill from public URLs or inline base64 content.

POST
Upload bill attachments/partners/bills/{uuid}/attachments/upload

Uploads files to a bill via multipart form data.

PATCH
Rename bill attachment/partners/bills/{uuid}/attachments/{attachmentUuid}

Changes the display title of one bill attachment.

DELETE
Delete bill attachment/partners/bills/{uuid}/attachments/{attachmentUuid}

Removes one file from a bill.

GET
Get bill attachment content/partners/bills/{uuid}/attachments/{attachmentUuid}/content

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