Practice Manager API

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

iduuid

Batch UUID.

referencestring

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

paymentDatedate

When the bank should pay.

fromAccountobject

The bank account paying.

iduuid

Account UUID.

namestring

Account name.

fromAccountNumberstring

Your own account number, embedded in some bank formats.

bankenum

The bank file format.

One of: asb, bnz, anz, kiwibank, westpac, generic

statementDetailsstring

What appears on your own statement.

totalstring

Sum of the lines' payment amounts.

createdByobject

Who created it (`id`, `firstName`, `lastName`, `email`). They cannot approve it.

linesarray

One per bill.

iduuid

Line UUID.

billobject

`id` and `billNumber`.

vendorobject

The supplier paid: `id` and `name`.

payeeBankAccountobject

`nzBankAccount` and `accountName` as copied when the bill was added.

particularsstring

Payment reference.

codestring

Payment reference; defaults to the bill number.

referencestring

Payment reference.

dueAmountstring

What the bill had outstanding.

paymentAmountstring

What this batch pays.

approversarray

Who must approve, with `user`, `status`, `assignedAt`, `approvedAt`, `rejectedAt` and `rejectionReason`.

downloadedAtdatetime

When the bank file was first generated.

paidAtdatetime

When it was paid.

Example
{
  "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.

Endpoints

GET
List payment batchesNZ· GST/firm-partners/workspace/payment-batches

Lists payment batches, newest first.

GET
List payment batch approversNZ· GST/firm-partners/workspace/payment-batches/approvers

Lists the workspace members who hold Approve Batch Payments. Needs Manage Batch Payments.

GET
Get a payment batchNZ· GST/firm-partners/workspace/payment-batches/{uuid}

Returns one batch with its lines and approvers.

POST
Create a payment batchNZ· GST/firm-partners/workspace/payment-batches

Creates an empty draft batch.

POST
Add bills to a payment batchNZ· GST/firm-partners/workspace/payment-batches/{uuid}/lines

Adds approved, unpaid bills to a draft batch, one line each.

DELETE
Remove a payment batch lineNZ· GST/firm-partners/workspace/payment-batches/{uuid}/lines/{lineUuid}

Removes one bill from a draft batch; the bill stays unpaid.

POST
Assign approversNZ· GST/firm-partners/workspace/payment-batches/{uuid}/approvers

Sends a draft batch for approval.

POST
Approve a payment batchNZ· GST/firm-partners/workspace/payment-batches/{uuid}/approve

Approves the batch as the connected user, an assigned approver.

POST
Reject a payment batchNZ· GST/firm-partners/workspace/payment-batches/{uuid}/reject

Rejects the batch as an assigned approver; it goes back to draft.

POST
Cancel a payment batchNZ· GST/firm-partners/workspace/payment-batches/{uuid}/cancel

Cancels an unpaid batch and releases its bills.

POST
Generate the bank fileNZ· GST/firm-partners/workspace/payment-batches/{uuid}/file

Returns the bank file of a ready batch and moves it to downloaded.