billy-mcp

List the chart of accounts in Billy. Use this to find account IDs for bill lines, product revenue accounts, and bank accounts for payments (look for isPaymentEnabled/isBankAccount).

Get a single account from the Billy chart of accounts by ID.

List daybook transactions (manual journal entries) in Billy, filterable by state and entry date range.

List files uploaded to Billy (receipts, invoices PDFs, etc.). Files are append-only via the API.

List attachments (file↔record links). Filter by owner to see what's attached to a specific record; ownerReference is applied client-side within the page.

Upload a local file (pdf/jpg/jpeg/png/gif ONLY — Billy rejects other types with a 422) to Billy and get its file ID. Files are append-only: they cannot be deleted or modified via the API afterwards. Use attach_file to link the uploaded file to a record.

Attach an uploaded file to a Billy record (daybook transaction, invoice, or bill). Get the fileId from upload_file or list_files. Example: attach a receipt to journal entry #67 → ownerType 'daybookTransaction', ownerId '<transaction id>'.

List supplier bills (expenses) in Billy with filters for supplier, state, paid status, date range and free-text search.

Get a single Billy bill by ID, including its lines, balance and paid status.

Create a supplier bill (expense) in Billy with one or more lines coded to expense accounts. Created as draft by default; pass state=approved to book it immediately.

List contacts (customers and suppliers) in Billy. Supports free-text search and filtering. Use this to find a contact ID before creating invoices or bills.

Get a single Billy contact by its ID, including full address and settings.

Create a new contact (customer or supplier) in Billy. Returns the created contact including its ID.

Update an existing Billy contact. Only provided fields are changed.

List contact persons (names/emails used for sending invoices) belonging to a Billy contact.

Add a contact person (name and/or email) to an existing Billy contact. Emails are used to mail invoices.

List daybooks in Billy. Find the daybook ID used for manual journal entries.

Create a manual journal entry (daybook transaction) in Billy with balanced debit/credit lines. Validates balance client-side before asking for approval. Supports safe-retry deduplication via idempotencyKey. Created as draft by default; state=approved books it immediately.

Void a daybook transaction (journal entry) in Billy. Irreversible — voided entries cannot be reinstated.

Void many daybook transactions in one call with ONE user approval for the whole batch. Continues past individual failures and reports per-id results. Irreversible.

List invoices in Billy with filters for customer, state, date range and free-text search. Returns invoices plus meta.paging.

Get a single Billy invoice by ID, including its lines, balance and paid status.

Create an invoice (or credit note) in Billy with one or more lines. Created as draft by default; pass state=approved to approve immediately (approval assigns the invoice number and books it). Amounts are in the invoice currency.

Approve a draft Billy invoice (draft -> approved is the only allowed state change). Approval books the invoice; it cannot be reverted to draft.

Delete a Billy invoice (drafts only; approved invoices must be voided/credited instead). Returns meta.deletedRecords.

Escape hatch: call any Billy API v2 endpoint not covered by a dedicated tool. Examples: GET /currencies, /countries, /taxRates, /salesTaxReturns, /invoiceReminders, /files, /bankLines, /postings, /users. Write requests must wrap the body in a singular resource key, e.g. { "daybookTransaction": {...}…

Get the Billy organization (company) details: name, base currency, VAT settings, default payment terms, fiscal year, invoice numbering. Call this first to learn the organization ID and base currency used by other tools.

Record a bank payment in Billy to mark an invoice or bill as (partially) paid. Creates a bankPayment associated with the subject via 'invoice:<id>' or 'bill:<id>'. For invoices money is deposited (debit); for bills it is withdrawn (credit). WARNING: this posts a real accounting transaction.

List bank payments recorded in Billy. Useful to review what payments exist for reconciliation. NOTE: Billy only supports organizationId server-side for this endpoint; contactId/cashAccountId/date filters are applied client-side within the fetched page.

List balance modifiers (payment associations) in Billy. Filter by subjectReference like 'invoice:<id>' or 'bill:<id>' to see which payments settled a specific invoice or bill. NOTE: subjectReference is not documented server-side; it is also enforced client-side within the fetched page.

List products in Billy. Use this to find a product ID before creating invoice lines. Supports free-text search.

Get a single Billy product by ID, plus its per-currency prices.

Create a product in Billy, optionally with per-currency unit prices. Returns the created product including its ID.

Update an existing Billy product. Only provided fields are changed. Providing prices replaces all existing prices.

Account balances / trial balance computed from postings. Ask "what is the balance of account 5211" → accountNos: ["5211"]. Omit account filters for a full trial balance. Bound with minEntryDate/maxEntryDate for speed — the tool fetches and aggregates all matching postings server-side.

List ledger postings (individual debit/credit entries). For balances/aggregates use get_account_balances instead. Date/void/text filters are applied client-side within the fetched page — narrow with accountId.

List booked transactions. transactionNo/voucherNo filters are applied CLIENT-SIDE (Billy silently ignores them as query params) by scanning up to 5000 records — bound with dates when possible.

List imported bank lines. Date and matched filters are applied client-side within the fetched page.

List bank line matches (bank reconciliation groupings). isApproved filter applied client-side within the page.

Run a short JavaScript (ES2022, top-level await allowed) batch script against the Billy API — use for loops, aggregation and reconciliation instead of many single tool calls (e.g. void 30 entries, post 7 monthly journals, sum postings). In scope: `billy` (get(path,query?), post(path,body), put(path,…