GET
List batches
Verifying a batch creates a draft — a record that these items are prepared and awaiting submission. Drafts are what let one person prepare a batch and another pay it.

​
List them

Returns batches that have been verified but not yet paid, newest first, with the same pagination as the normal listing. Omit drafts and you get submitted batches exactly as before — a draft never appears in the default list. A draft appears in this list as soon as verification is requested, not when it finishes, so a freshly prepared one may still be verifying. Opening it before the check completes returns the draft with payloadStatus: "PENDING" and no payments. Each entry carries:
Drafts have no item rows until they’re paid, so itemsStatus and totalAmount are absent on a draft — not zero, and they stay absent even if you ask for includeItemSummary=true. paymentsCount is what a draft has instead.

​
Open one

For a draft, the response carries a draft object instead of items — with the verified payments split into validPayments and invalidPayments, so you can see exactly what was checked before deciding to pay. For a batch that has already been paid, the same call returns its item rows as it always has.

​
Withdraw one

Takes back a batch you prepared but never paid. The draft is removed, and the verified payload behind it — the payee names, accounts and amounts that were checked — is deleted with it. Only drafts can be deleted. A batch you have already paid has money in flight behind it and returns 409. An expired draft can still be deleted, which is how you clear one out of the list. Deleting is final for that draft, and it is not idempotent: once it is gone there is nothing left to recognise, so calling again returns 404 rather than succeeding twice. To prepare the same payments once more, verify them — that creates a new draft.

​
Expiry

A draft expires 7 days after it was first verified, or at the end of its earliest scheduledDate, whichever comes first. An expired draft still appears in the list, marked EXPIRED — the record that a batch was prepared and never sent is worth keeping. But it can no longer be submitted, and opening it returns the draft without its payload, because the verified items are held on their own retention clock.
To recover an expired draft, verify the items again. That creates a new draft with a fresh batchId and expiry.

​
Who can see what

You only ever see your own drafts — including one a back-office operator prepared for you. Drafts prepared through the back-office route belong to the team that prepared them, and opening a draft you don’t own is refused as if it did not exist.

Authorizations

​
Authorization
string
header
required

The caller's id_token from authentication — the ID token, not the access_token. The program and environment come from the token.

Query Parameters

​
limit
integer
default:50

Maximum number of batches to return. Values above 1000 are clamped to 1000. Invalid values include 0, negative numbers, non-integer strings, and mixed strings such as 10abc.

Required range: x >= 1
​
nextToken
string

Pagination token returned by a previous response.

​
lookbackDays
integer
default:30

Lookback window for program-admin searches. Invalid values include 0, negative numbers, non-integer strings, and mixed strings such as 10abc.

Required range: x >= 1
​
drafts
enum<string>

Set to true to list batches awaiting submission instead of submitted ones. Omit it and the response is unchanged. Drafts are held in separate indexes, so this selects a different query rather than filtering the normal one — a draft never appears in the default listing. Only the exact string true enables it.

Available options:
true
​
includeItemSummary
enum<string>

Set to true to include the per-batch item summary — itemsStatus (counts by item status) and totalAmount (the sum of item amounts). Omit it and both fields are absent. Available to every role, including customer callers. Only the exact string true enables it. Has no effect with drafts=true, which has no item rows to summarise.

Available options:
true

Response

Batches. The example shows a response to ?includeItemSummary=true.

​
success
boolean
Example:

true

​
data
object