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-10-03

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` and `customerUuid`, `tagUuids`, and `projectUuid`. Numeric `vendorId`, `categoryAccountId`, and `tags` are rejected.

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), 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.

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.

Filter by vendor

Pass comma-separated vendor UUIDs in vendorUuids (from the Vendors API). Do not pass numeric vendors.

Recent changes

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.