Practice Manager API
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 /firm-partners/workspace/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 /firm-partners/workspace/bills, and list them with GET /firm-partners/workspace/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 /firm-partners/workspace/transactions/{transactionId}/assign-to-bills-invoices (matchingType bill) takes a partial paymentAmount and is the only route for foreign-currency bills. POST /firm-partners/workspace/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
Endpoints
/firm-partners/workspace/billsReturns a paginated list of bills and vendor memos in the workspace.
/firm-partners/workspace/bills/{uuid}Retrieves a single bill by its UUID.
/firm-partners/workspace/billsCreates a new vendor bill (draft by default, or approved for migrations).
/firm-partners/workspace/bills/{uuid}Updates a bill. Only the fields you send are changed.
/firm-partners/workspace/bills/{uuid}Soft-deletes a draft bill.
/firm-partners/workspace/bills/{uuid}/submitSubmits a draft or rejected bill for approval and posts its accrual journal.
/firm-partners/workspace/bills/{uuid}/approveApproves a draft bill and posts journal entries.
/firm-partners/workspace/bills/{uuid}/apply-vendor-memosApplies one or more vendor credit memos toward an approved bill.
/firm-partners/workspace/bills/{uuid}/unassign-vendor-memosRemoves a vendor credit memo previously applied to a bill.
/firm-partners/workspace/bills/{uuid}/assign-transactionSettles one or more whole transactions against an approved bill or vendor memo.
/firm-partners/workspace/bills/{uuid}/unassign-transactionRemoves a previously applied expense transaction payment from a bill.
/firm-partners/workspace/bills/{uuid}/attachmentsLists the files attached to a bill or vendor memo.
/firm-partners/workspace/bills/{uuid}/attachmentsAdds files to a bill from public URLs or inline base64 content.
/firm-partners/workspace/bills/{uuid}/attachments/uploadUploads files to a bill via multipart form data.
/firm-partners/workspace/bills/{uuid}/attachments/{attachmentUuid}Changes the display title of one bill attachment.
/firm-partners/workspace/bills/{uuid}/attachments/{attachmentUuid}Removes one file from a bill.
/firm-partners/workspace/bills/{uuid}/attachments/{attachmentUuid}/contentReturns one bill attachment's file, base64-encoded.
