API Reference
Payment Batches
Pay many approved bills together with one bank file: build a batch, send it for approval, then generate the file to upload to the bank. New Zealand workspaces only.
Last updated 2026-11-18
Some fields work differently in US and NZ workspaces
Showing US sales tax and NZ GST rules.
Overview
A payment batch is a set of approved, unpaid bills paid from one bank account on one date. Each line copies the supplier's bank account (see Supplier Bank Accounts) and payment references when the bill is added.
Flow: create a draft → add bills → assign approvers → each approver approves (the batch becomes `ready`) → generate the bank file (`downloaded`) → upload it to the bank. The bills are paid when the bank line is matched in COUNT.
Key concepts
NZ· GSTNew Zealand only
Bank files are New Zealand direct-credit formats, so these routes work in NZ workspaces only. Any other workspace gets 400.
Approval needs a second person
Whoever creates a batch cannot approve it, and the API acts as the connected user. So a batch built through your integration is approved by someone else: through their own connection, or in COUNT. List who can approve with GET /approvers. Where the workspace does not require approvers, assigning an empty list makes the batch `ready` at once.
Generating the bank file
POST /{uuid}/file returns the file (`fileName`, `contentType`, `contentBase64`) for a `ready` batch and moves it to `downloaded`; it can be generated again until the batch is paid. Payments happen only when you upload the file to the bank.
The payment batch object
Attributes
iduuidBatch UUID.
referencestringBATCH-YYMMDD-NN, unique in the workspace.
statusenum`draft` while being built or awaiting approval, `ready` once approved, `downloaded` once its file was generated.
One of: draft, ready, downloaded, sent, paid, reconciled, cancelled
paymentDatedateWhen the bank should pay.
fromAccountobjectThe bank account paying.
iduuidAccount UUID.
namestringAccount name.
fromAccountNumberstringYour own account number, embedded in some bank formats.
bankenumThe bank file format.
One of: asb, bnz, anz, kiwibank, westpac, generic
statementDetailsstringWhat appears on your own statement.
totalstringSum of the lines' payment amounts.
createdByobjectWho created it (`id`, `firstName`, `lastName`, `email`). They cannot approve it.
linesarrayOne per bill.
iduuidLine UUID.
billobject`id` and `billNumber`.
vendorobjectThe supplier paid: `id` and `name`.
payeeBankAccountobject`nzBankAccount` and `accountName` as copied when the bill was added.
particularsstringPayment reference.
codestringPayment reference; defaults to the bill number.
referencestringPayment reference.
dueAmountstringWhat the bill had outstanding.
paymentAmountstringWhat this batch pays.
approversarrayWho must approve, with `user`, `status`, `assignedAt`, `approvedAt`, `rejectedAt` and `rejectionReason`.
downloadedAtdatetimeWhen the bank file was first generated.
paidAtdatetimeWhen it was paid.
{
"id": "0193a1c2-7b4d-7e10-9a2f-5c6d7e8f9b01",
"reference": "BATCH-261120-01",
"status": "draft",
"paymentDate": "2026-11-20",
"fromAccount": {
"id": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a10",
"name": "ASB Business"
},
"fromAccountNumber": "12-3456-7890123-00",
"bank": "asb",
"bankCountry": "NZ",
"statementDetails": "Supplier run",
"total": "1250.0000",
"createdBy": {
"id": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a03",
"firstName": "Ana",
"lastName": "Reyes",
"email": "ana@example.com"
},
"downloadedAt": null,
"sentAt": null,
"paidAt": null,
"reconciledAt": null,
"createdAt": "2026-01-15T10:30:00.000Z",
"updatedAt": "2026-01-28T14:22:30.000Z",
"lines": [
{
"id": "0193a1c2-7b4d-7e10-9a2f-5c6d7e8f9b02",
"bill": {
"id": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a01",
"billNumber": "INV-0042"
},
"vendor": {
"id": "d4e5f6a7-b8c9-0123-defa-234567890123",
"name": "Harbourside Office Supplies Ltd"
},
"payeeBankAccount": {
"nzBankAccount": "12-3456-7890123-001",
"accountName": "Harbourside Office Supplies"
},
"particulars": "Acme Ltd",
"code": "INV-0042",
"reference": "ACME-001",
"dueAmount": "1250.0000",
"paymentAmount": "1250.0000",
"reconciledAt": null
}
],
"approvers": [
{
"user": {
"id": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a02",
"firstName": "Ben",
"lastName": "Ito",
"email": "ben@example.com"
},
"status": "pending",
"assignedAt": "2026-01-28T14:22:30.000Z",
"approvedAt": null,
"rejectedAt": null,
"rejectionReason": null
}
]
}Scope and permissions
Needs the `payment-batches` scope (`:read` to list and get, `:write` for everything else, including generating the file). Neither `bills:*` nor a bare `read` / `write` grant includes it, for apps and firm keys alike; only COUNT's own MCP connector has it with full access. The connecting user needs View Batch Payments to read, Manage Batch Payments to build, cancel and list who can approve, and Approve Batch Payments to approve, reject and generate the file.MCP equivalent
COUNT_list_payment_batches, COUNT_list_payment_batch_approvers, COUNT_get_payment_batch, COUNT_create_payment_batch, COUNT_add_bills_to_payment_batch, COUNT_remove_payment_batch_line, COUNT_assign_payment_batch_approvers, COUNT_approve_payment_batch, COUNT_reject_payment_batch, COUNT_cancel_payment_batch and COUNT_get_payment_batch_bank_file. Approve, reject, cancel, removing a line and generating the bank file ask the user to confirm on clients that support it. They are not offered inside COUNT AI chat.Related
Recent changes
Payment batches
In New Zealand workspaces, /partners/payment-batches builds and pays batch payments: GET lists batches (status, limit, offset) and GET /{uuid} returns one with its lines and approvers; POST creates a draft, POST /{uuid}/lines adds approved bills, DELETE /{uuid}/lines/{lineUuid} removes one, POST /{uuid}/approvers sends it for approval (GET /approvers lists who can approve), POST /{uuid}/approve and /reject decide it, POST /{uuid}/cancel cancels it, and POST /{uuid}/file returns the bank file of a ready batch and moves it to downloaded. Whoever creates a batch cannot approve it. These routes need the new `payment-batches` scope, which neither `bills` nor a bare `read` / `write` grant includes (COUNT's own MCP connector excepted), and the batch payment permissions. The same routes work on client workspaces under /firm-partners/workspace. The MCP catalog adds 11 payment batch tools, which are not offered inside COUNT AI chat.
Endpoints
/partners/payment-batchesLists payment batches, newest first.
/partners/payment-batches/approversLists the workspace members who hold Approve Batch Payments. Needs Manage Batch Payments.
/partners/payment-batches/{uuid}Returns one batch with its lines and approvers.
/partners/payment-batchesCreates an empty draft batch.
/partners/payment-batches/{uuid}/linesAdds approved, unpaid bills to a draft batch, one line each.
/partners/payment-batches/{uuid}/lines/{lineUuid}Removes one bill from a draft batch; the bill stays unpaid.
/partners/payment-batches/{uuid}/approversSends a draft batch for approval.
/partners/payment-batches/{uuid}/approveApproves the batch as the connected user, an assigned approver.
/partners/payment-batches/{uuid}/rejectRejects the batch as an assigned approver; it goes back to draft.
/partners/payment-batches/{uuid}/cancelCancels an unpaid batch and releases its bills.
/partners/payment-batches/{uuid}/fileReturns the bank file of a ready batch and moves it to downloaded.
