# 

These are the endpoints you reconcile against. A deposit in the merchant's bank
account corresponds to a batch, not to a transaction, so matching the two means
reading batches.

| Endpoint | Use it to |
|  --- | --- |
| `GET /v1/batches` | List batches |
| `GET /v1/batches/status` | Check what has changed since you last looked |
| `GET /v1/batches/{id}/transactions` | Read a known batch's transactions |
| `GET /v1/batches/transactions` | Read the open batch, before it has an ID |


## List batches

**This endpoint pages differently from the transaction endpoints.** It takes
`skip` and `take` where transactions take `offset` and `limit`, and `sort_column`
where transactions take `sort_by`. The two were built at different times and have
not been reconciled.

| Here | On `GET /v1/transactions` |
|  --- | --- |
| `skip` | `offset` |
| `take` | `limit` |
| `sort_column` | `sort_by` |
| `search_text`, `term` | no equivalent |


### Filter with `term`

`term` narrows the list by date, status and time zone. It takes a comma-separated list of pieces:

| Piece | Form | How many |
|  --- | --- | --- |
| Date | `createdate` with `>=`, `<=`, `>`, `<` or `=`, against a quoted ISO 8601 timestamp | Repeat it to bound a range |
| Status | `status=` with `opened`, `closed`, `in_progress` or `failed` | One |
| Time zone | An IANA time zone name, such as `America/Chicago`, or `UTC` | One |


For example, the closed batches in September, by Chicago's calendar:

```text
createdate>='2026-09-01T00:00:00Z',createdate<='2026-09-30T23:59:59Z',status=closed,America/Chicago
```

A timestamp with no offset is read as UTC. The time zone decides which calendar day an open batch falls on, and is UTC when you leave it out.

**Check each piece before you send it.** The gateway refuses a `term` holding anything else, and today it answers `500` with `SYSTEM_ERROR`, not `400`. So a typo in a filter reads like a server fault.

### Read a batch's status

Each batch in the list carries `status`, by name:

| `status` | Means |
|  --- | --- |
| `Opened` | Not yet sent for settlement. An open batch has no `batch_id` |
| `In-Progress` | Sent for settlement and awaiting the result |
| `Closed` | Settled by the processor |
| `Failed` | The close failed |


Compare them exactly as written: capitalized, with a hyphen in `In-Progress`. The `term` filter spells the same statuses in lowercase, with an underscore in `in_progress`.

## Check for changes

`last_checked_at` returns what has changed since that timestamp, which makes this
the endpoint to poll on a schedule rather than re-listing everything.

**This endpoint reports status as a code, not a name.** `status` is a string holding a number:

| `status` | Where | Means |
|  --- | --- | --- |
| `"10"` | Every batch in `in_progress_batches` | In progress: the batch is closing |
| `"2"` | `completed_batches` | Closed: the batch closed successfully |
| `"5"` | `completed_batches` | Failed: the batch close failed |


These are the same statuses `GET /v1/batches` reports as `In-Progress`, `Closed` and `Failed`. Read each endpoint's `status` in its own vocabulary, and compare the codes as strings, not numbers.

## Read a batch's transactions

Once a batch has an ID, ask for its contents directly.

`include_bad_transactions` defaults to `false`. Turn it on when you are
investigating a mismatch — a batch total that does not agree with your own
figures often has an excluded transaction behind it.

## Read the open batch

A batch has no ID until it exists, so there is a separate endpoint for the batch
that is still accumulating.

Use it to see what will settle at the next close. It takes `client_id`,
`integration`, `created_at`, a `timezone` from the supported list, and
`card_type`.

**`card_type` here is not the same parameter as on `GET /v1/transactions`.** It is
narrower:

|  | `GET /v1/transactions` | `GET /v1/batches/transactions` |
|  --- | --- | --- |
| Accepts | `CREDIT`, `DEBIT`, `UNKNOWN` | `CREDIT`, `DEBIT` |
| Comma-separated list | Yes | No |
| `UNKNOWN` | Matches undetermined rows | Returns `400` |


On this endpoint `CREDIT` also returns the rows whose card type was never
determined, which is the behavior `UNKNOWN` gives you on the other one.

## Reconciling

The order that works:

1. Poll `GET /v1/batches/status` with `last_checked_at` to find closed batches, the ones whose `status` is `"2"`.
2. For each, read `GET /v1/batches/{id}/transactions`.
3. Match the batch total against the deposit.
4. When they disagree, re-read with `include_bad_transactions=true`.


For ACH, keep watching after settlement. A return can arrive days later and will
not appear in the batch you already reconciled. See
[Find and report on transactions](/docs/after-the-payment/find-and-report-on-transactions).

## Next steps

* [Batches and settlement](/docs/after-the-payment/batches-and-settlement)
* [Find and report on transactions](/docs/after-the-payment/find-and-report-on-transactions)
* [Client reports](/docs/platforms/client-reports)