---
title: "Bills · Practice Manager API · COUNT Partner API"
description: "Bills are vendor payables — amounts your workspace owes to suppliers. Partner routes cover listing, creating, updating, approving, and deleting bills…"
canonical: "https://developers.getcount.com/practice-manager/reference/bills"
source: "https://developers.getcount.com/practice-manager/reference/bills"
---
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

`id` uuid

Bill identifier (UUID). Use in path parameters.

`billNumber` string

Human-readable bill number.

`billType` enum

Document type. Vendor memos are credits from the vendor.

One of: `bill`, `vendor_memo`

`date` date

Bill date (ISO).

`dueDate` date

Payment due date (ISO).

`currency` string

ISO 4217 currency code.

`approvalStatus` enum

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

One of: `draft`, `submitted`, `approved`, `rejected`

`status` string

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

`total` number

Bill total including tax.

`paidAmount` number

Amount already paid or applied.

`amountDue` number

Outstanding balance.

`notes` string

Free-text notes.

`purchaseOrderNumber` string

Optional PO reference.

`isDeleted` boolean

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

`vendor` object

Linked vendor record, including address when present.

`lineItems` array

Expense lines on the bill.

`description` string

Line description.

`quantity` number

Quantity.

`price` number

Unit price.

`total` number

Line total.

`categoryAccountUuid` uuid

Expense or category account UUID.

`projectUuid` uuid

Optional project UUID on the line.

`customerUuid` uuid

Optional customer UUID for billable expenses.

`appliedTax` object

The line's tax code, or null.

- US· Sales tax Always null; bills carry no tax.
- NZ· GST The line's GST code.

`taxName` string

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

`taxPercentage` number

Rate applied to the line.

`tax` number

Tax amount on the line.

- US· Sales tax Always 0.
- NZ· GST The GST on the line.

`transactions` array

Expense transactions applied as payment.

`appliedVendorMemos` array

Vendor memos applied toward this bill.

`createdAt` datetime

ISO 8601 creation timestamp.

`updatedAt` datetime

ISO 8601 last update timestamp.

Example

```json
{
  "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

- [Transactions API](https://developers.getcount.com/practice-manager/reference/transactions)
- [Vendors API](https://developers.getcount.com/practice-manager/reference/vendors)
- [Chart of Accounts API](https://developers.getcount.com/practice-manager/reference/chart-of-accounts)

## Endpoints

[GET List bills `/firm-partners/workspace/bills` Returns a paginated list of bills and vendor memos in the workspace.](https://developers.getcount.com/practice-manager/reference/bills/list-bills) [GET Get a bill `/firm-partners/workspace/bills/{uuid}` Retrieves a single bill by its UUID.](https://developers.getcount.com/practice-manager/reference/bills/get-bill) [POST Create a bill `/firm-partners/workspace/bills` Creates a new vendor bill (draft by default, or approved for migrations).](https://developers.getcount.com/practice-manager/reference/bills/create-bill) [PATCH Update a bill `/firm-partners/workspace/bills/{uuid}` Updates a bill. Only the fields you send are changed.](https://developers.getcount.com/practice-manager/reference/bills/update-bill) [DELETE Delete a bill `/firm-partners/workspace/bills/{uuid}` Soft-deletes a draft bill.](https://developers.getcount.com/practice-manager/reference/bills/delete-bill) [POST Submit a bill `/firm-partners/workspace/bills/{uuid}/submit` Submits a draft or rejected bill for approval and posts its accrual journal.](https://developers.getcount.com/practice-manager/reference/bills/submit-bill) [POST Approve a bill `/firm-partners/workspace/bills/{uuid}/approve` Approves a draft bill and posts journal entries.](https://developers.getcount.com/practice-manager/reference/bills/approve-bill) [POST Apply vendor memos to a bill `/firm-partners/workspace/bills/{uuid}/apply-vendor-memos` Applies one or more vendor credit memos toward an approved bill.](https://developers.getcount.com/practice-manager/reference/bills/apply-vendor-memos-to-bill) [POST Unassign a vendor memo from a bill `/firm-partners/workspace/bills/{uuid}/unassign-vendor-memos` Removes a vendor credit memo previously applied to a bill.](https://developers.getcount.com/practice-manager/reference/bills/unassign-vendor-memo-from-bill) [POST Assign transactions as payment `/firm-partners/workspace/bills/{uuid}/assign-transaction` Settles one or more whole transactions against an approved bill or vendor memo.](https://developers.getcount.com/practice-manager/reference/bills/assign-bill-transaction) [POST Unassign a transaction payment `/firm-partners/workspace/bills/{uuid}/unassign-transaction` Removes a previously applied expense transaction payment from a bill.](https://developers.getcount.com/practice-manager/reference/bills/unassign-bill-transaction) [GET List bill attachments `/firm-partners/workspace/bills/{uuid}/attachments` Lists the files attached to a bill or vendor memo.](https://developers.getcount.com/practice-manager/reference/bills/list-bill-attachments) [POST Add bill attachments `/firm-partners/workspace/bills/{uuid}/attachments` Adds files to a bill from public URLs or inline base64 content.](https://developers.getcount.com/practice-manager/reference/bills/add-bill-attachments) [POST Upload bill attachments `/firm-partners/workspace/bills/{uuid}/attachments/upload` Uploads files to a bill via multipart form data.](https://developers.getcount.com/practice-manager/reference/bills/upload-bill-attachments) [PATCH Rename bill attachment `/firm-partners/workspace/bills/{uuid}/attachments/{attachmentUuid}` Changes the display title of one bill attachment.](https://developers.getcount.com/practice-manager/reference/bills/update-bill-attachment) [DELETE Delete bill attachment `/firm-partners/workspace/bills/{uuid}/attachments/{attachmentUuid}` Removes one file from a bill.](https://developers.getcount.com/practice-manager/reference/bills/delete-bill-attachment) [GET Get bill attachment content `/firm-partners/workspace/bills/{uuid}/attachments/{attachmentUuid}/content` Returns one bill attachment's file, base64-encoded.](https://developers.getcount.com/practice-manager/reference/bills/get-bill-attachment-content)
