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-07-07

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}/approve posts journal entries and makes the bill eligible for payment. Pay with POST /partners/transactions/{uuid}/assign-to-bills-invoices (Expense transaction) or apply vendor memos.

Lifecycle and allowed operations

Typical flow: create (draft) → approve → pay via assign-to-bills-invoices or vendor memos. update/delete work on drafts only; approve is idempotent on already-approved bills; there is no revert-to-draft API.

Vendor memos

List vendor memos with GET /partners/bills?billType=vendor_memo. Apply them to an approved bill with POST /{uuid}/apply-vendor-memos. Each memo must belong to the same vendor and have sufficient balance.

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.

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

Whether the bill has been approved for payment.

One of: draft, approved

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"
}

Pay bills via Transactions API

There is no bill-specific assign-transaction route. Apply bank/expense payments with POST /partners/transactions/{transactionId}/assign-to-bills-invoices and matchingType bill.

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