API Reference
Taxes
Create, read, update and delete the tax codes (tax rates) of the authenticated workspace, and look up a US sales tax rate for an address. Send the tax UUIDs on transactions, invoice and bill lines, products, and accounts.
Last updated 2026-11-18
Some fields work differently in US and NZ workspaces
Showing US sales tax and NZ GST rules.
Overview
Every route that takes a tax code — `taxes` or `taxUuids` on transactions, invoice lines, products, and accounts, and `taxUuid` on bill lines — expects the tax UUID. GET /partners/taxes is where those UUIDs come from. Numeric tax ids are never accepted.
Tax codes can be created, renamed, re-rated, switched off and deleted through the Partner API, with the same rules as the COUNT app: two codes cannot share a name and rate, system codes cannot be renamed, re-rated or deleted, and a code that has been posted to the ledger keeps its rate.
Each new code gets its own liability account, `Tax: <name>`. In a US workspace that account sits under a shared Sales Tax Payable parent account.
Key concepts
US· Sales taxSales tax codes
Sales tax codes are created by the workspace, each with its jurisdiction in `country`, `state`, `county`, `city`, `zipCode` and `locationCode`. Look up a rate for an address with GET /partners/taxes/sales-tax-rate. Invoice lines charge the codes in `taxes`; `nonTaxable: true` keeps the code and reports the sale as Non-Taxable under it. Bills carry no tax: a bill line's `taxUuid` is ignored.
NZ· GSTGST codes
Every NZ workspace has five GST codes COUNT creates: `15% GST on Income` (15%), `15% GST on Expenses` (15%), `Zero Rated` (0%), `No GST` (0%), and `GST on Imports` (100% — the line amount is the GST itself). Use them by UUID on invoice lines (`taxes`) and bill lines (`taxUuid`). `nonTaxable: true` on an invoice line clears its code; it does not zero-rate it.
NZ· GSTWhere each GST code reports
`15% GST on Income` — sales, GST return box 5. `Zero Rated` — sales, boxes 5 and 6 (zero-rated supplies). `15% GST on Expenses` — purchases, box 11. `GST on Imports` — box 13 (credit adjustments). `No GST` — not on the return. Zero Rated and No GST are both 0%, so choose by how the supply must be reported.
NZ· GSTWhich GST code fits which account
Income accounts take `15% GST on Income` or `Zero Rated`. Expenses accounts take `15% GST on Expenses`. Assets accounts take either side. Liabilities and Equity accounts take no GST code. `GST on Imports` is valid only on the GST on Imports account, and `No GST` fits any account. Any other pairing on an invoice or bill line is refused with 400.
Tax code
Attributes
iduuidTax UUID. Send this wherever a route takes a tax code.
namestringDisplay name.
percentagestringRate as a decimal string with four places, e.g. `"15.0000"`.
typestringTax type, e.g. `"Sales Tax"`.
descriptionstringDescription, or null.
enabledbooleanWhether the code is in use.
editableboolean`false` for system codes COUNT manages.
systemCreatedbooleanWhether COUNT created the code.
countrystringJurisdiction country for US sales-tax codes; null otherwise. The same applies to `state`, `county`, `city`, `zipCode`, and `locationCode`.
{
"id": "3f6c2a1e-8b4d-4e7a-9c2f-1d5e8a7b6c40",
"name": "CA Sales Tax",
"percentage": "7.2500",
"type": "Sales Tax",
"description": "California state sales tax",
"enabled": true,
"editable": true,
"systemCreated": false,
"country": "US",
"state": "CA",
"county": null,
"city": null,
"zipCode": null,
"locationCode": null
}Scope and permissions
Reads (list, get, sales tax rate) need the `workspace:read` scope, and the connecting user needs any one of `view_accounts`, `view_invoices`, `view_bills`, `view_transactions`, or `manage_taxes`. Create, update and delete need `workspace:write` and `manage_taxes`.MCP equivalent
COUNT_list_taxes, COUNT_get_tax, COUNT_create_tax, COUNT_update_tax, COUNT_delete_tax and COUNT_get_sales_tax_rate. On a client that can show a form, COUNT_delete_tax asks the user to confirm first.Related
Recent changes
Incremental sync: updatedSince on every list endpoint, includeDeleted, and the deleted-records feed
Every Partner API list endpoint now takes updatedSince, so an integration can pull only what changed instead of re-reading whole lists. Pass an ISO 8601 date-time and the list returns the records created or changed at or after it, oldest change first, with nextUpdatedSince and hasMore beside the rows; pass nextUpdatedSince back as updatedSince to read the next page, and keep it for the next poll once hasMore is false. Paging by cursor means a record changed mid-walk can no longer move between pages and be skipped, so updatedSince cannot be combined with page above 1 or a sort. includeDeleted=true returns deleted records with isDeleted: true on vendors, customers, products, people, taxes, projects, project tasks, tasks, time entries, recurring invoice templates, the chart of accounts, transactions, invoices, and bills. The chart of accounts returns a flat list of changed accounts in this mode, each naming its parent in parentAccountUuid. Records removed outright — tags, tag groups, journal entry lines, expense receipts, customer contacts, addresses and notes, budgets, and any other hard delete — are listed by the new GET /partners/deleted-records, which keeps 90 days. updatedFrom and updatedTo stay on transactions, invoices, and bills, now read as UTC when they carry no offset. The new Keeping in Sync guide (/guides/keeping-in-sync) puts the pieces together into a 15-minute poll with a sync-now button. The MCP catalog adds COUNT_list_deleted_records, and every list tool takes updatedSince (and includeDeleted where it applies) under query.
Line taxes on invoices and bills, split by US and NZ
Documented the line tax fields the reference was missing and how each behaves in US and NZ workspaces. Bill lines take one tax code in `lineItems[].taxUuid` (NZ: the GST code; US: ignored, bills carry no tax), and bill responses show it as `appliedTax`. Invoice, credit memo and recurring template lines take tax code UUIDs in `taxes`, the document takes `productsPriceType` (`tax-exclusive` or `tax-inclusive`), and `nonTaxable` and `customerExemptionOverridden` now say what they do in each country: in the US a Non-Taxable line keeps its code, in NZ it is cleared. The Taxes page lists the five NZ GST codes, where each reports on the GST return (Zero Rated in boxes 5 and 6, No GST nowhere), and which accounts each fits. Customer `taxExcluded` is a tax exemption, not tax-exclusive pricing, and customer and account `taxes` take tax UUIDs. A US / NZ switch in the header, and on every page with country-specific rules, shows one country's notes at a time; links can open in either view with `?region=us` or `?region=nz`.
Create, edit and delete tax codes and people
Tax codes are no longer read-only. GET, PATCH and DELETE /partners/taxes/{uuid} and POST /partners/taxes get, create, edit (name, rate, description, enabled) and delete a code, with the COUNT app's rules: no two codes with the same name and rate, system codes keep their name and rate, a code posted to the ledger keeps its rate, and the rate cannot be negative. GET /partners/taxes/sales-tax-rate looks up the US sales tax rate for an address without saving anything. People gain POST /partners/people, PATCH and DELETE /partners/people/{uuid}, PATCH .../enabled (send the status you want), PATCH .../terminate, POST .../resend-invite, POST .../resend-onboarding-email, POST and DELETE .../expense-reporter, and list, get, create, update and delete under .../jobs, where a job's title names an existing position. Bank accounts, tax identification numbers and adding or removing the payroll role stay in the COUNT app, and person responses no longer include sign-in tokens, tax identification numbers (including on a contractor's vendor), bank account numbers or internal ids. Tax writes need workspace:write; people writes need people:write. The same routes work on a client workspace through the Practice Manager API under /firm-partners/workspace. The MCP catalog adds 17 tools: COUNT_get_tax, COUNT_create_tax, COUNT_update_tax, COUNT_delete_tax, COUNT_get_sales_tax_rate, COUNT_delete_person, COUNT_set_person_enabled, COUNT_terminate_person, COUNT_resend_person_invite, COUNT_resend_payroll_onboarding_email, COUNT_add_expense_reporter, COUNT_remove_expense_reporter, and five person job tools.
Cash flow forecast, GST return and audit report, tax codes, workspace events, and 17 MCP tools
Documented the six partner routes the reference was missing. POST /partners/reports/cash-flow-forecast forecasts cash for the next 13 weeks, with an optional what-if scenario (customer payment delays, bill payment dates and one-off or repeating adjustments) returned as scenarioForecast. GET /partners/reports/gst-return calculates an NZ GST return without filing it, including the reconciliation that decides whether COUNT would let it file, and GET /partners/reports/gst-audit-report lists the transactions behind it, flags the ones with a GST issue, and pages 200 rows at a time. GET /partners/taxes lists the workspace tax codes and their UUIDs. GET /partners/workspace-events returns what changed since the user last checked: invoices paid, failed invoice payments, new bills and bank feed syncs. GET /partners/journal-entries/{uuid} returns one posting with every line. Taxes and workspace events are also reachable through the Practice Manager client-workspace routes. npm run check:parity now reports 186 documented routes against 186 backend routes. The MCP catalog adds COUNT_list_taxes, COUNT_list_workspace_events, COUNT_get_journal_entry, COUNT_generate_cash_flow_forecast, COUNT_get_gst_return, COUNT_get_gst_audit_report, COUNT_propose_transaction_categories, four position tools (COUNT_get_all_positions, COUNT_create_position, COUNT_update_position, COUNT_delete_position), and five firm tools for client status and client questionnaires. COUNT_delete_project is now COUNT_archive_project, and DELETE /partners/projects/{uuid} is documented as the archive it is, with its real response (result.success). Also, COUNT_get_bulk_task_status, which the server no longer registers, is removed.
Endpoints
/partners/taxesReturns every tax code in the workspace, optionally filtered by whether it is enabled.
/partners/taxes/{uuid}Returns one tax code by UUID.
/partners/taxesCreates a tax code and its liability account.
/partners/taxes/{uuid}Renames, re-rates, describes, or switches a tax code on or off.
/partners/taxes/{uuid}Deletes a tax code.
/partners/taxes/sales-tax-rateReturns the combined US sales tax rate for an address. Nothing is saved.
