> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionicfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The terminal batch object

> Read Ionic's batch, batch item, and settlement profile records for card-present payments.

<ResponseExample>
  ```json The terminal batch object theme={null}
  {
    "id": "tmb_01JEXAMPLE2K8V4N9C6M1Q7R",
    "object": "terminal_batch",
    "status": "open",
    "reconciliation_status": "not_started",
    "terminal_ids": [],
    "currency": "usd",
    "transaction_count": 1,
    "totals": {
      "sales": 2500,
      "refunds": 2500,
      "voids": 2500,
      "tips": 2500,
      "fees": 2500,
      "tax": 2500,
      "net": null
    },
    "opened_at": 1767225600,
    "closed_at": null,
    "livemode": false
  }
  ```
</ResponseExample>

A Terminal batch (`tmb_…`) is Ionic's persisted record of a batch of
card-present transactions for one or more [Terminals](/api-reference/terminals). It reports a lifecycle `status`, a
`reconciliation_status`, transaction counts, and totals in minor units. Batch
items (`tbi_…`) are the transaction records in a batch's latest snapshot, linked
to a Charge or Refund where one exists. A settlement profile (`stlp_…`) is a
stable Ionic grouping that you can use to filter batches without relying on
hardware-specific or processing-specific identifiers.

Batches are read-only. Ionic never clears, forces, or closes a batch through
this API. Listing batches does not contact a Terminal, so use `data_as_of`,
`stale_after`, and `is_stale` to decide whether to refresh. See
[The Terminal object](/concepts/terminal-object) for how Terminal refunds relate to
batch settlement, and [Accept in-person terminal payments](/guides/in-person-payments) for the
payment flow.

## Attributes

<ResponseField name="id" type="string">
  Unique identifier for the batch (`tmb_…`).
</ResponseField>

<ResponseField name="status" type="string">
  Whether the batch is `open`, `closing`, or `closed`.
</ResponseField>

<ResponseField name="reconciliation_status" type="string">
  Whether the batch's transactions have been matched to your charges and refunds. `reconciled` means every transaction is matched.
</ResponseField>

<ResponseField name="terminal_ids" type="array of strings">
  IDs of the terminals whose transactions are in this batch (`tmr_…`).
</ResponseField>

<ResponseField name="currency" type="string">
  Three-letter ISO currency code, in lowercase.
</ResponseField>

<ResponseField name="transaction_count" type="integer">
  Number of transactions in the batch.
</ResponseField>

<ResponseField name="totals" type="object">
  Money totals for the batch, in the smallest currency unit.
</ResponseField>

<ResponseField name="opened_at" type="integer">
  Unix epoch seconds when the batch opened.
</ResponseField>

<ResponseField name="closed_at" type="integer | null">
  Unix epoch seconds when the batch closed. Null until it closes.
</ResponseField>

See every field in the response of [Retrieve a Terminal batch](/api-reference/terminal-batches/retrieve-a-terminal-batch).

## Endpoints

| Endpoint | Use it for |
| - | - |
| [Refresh a Terminal's current batches](/api-reference/terminal-batches/refresh-a-terminals-current-batches) | Refresh Ionic's batch information for one Terminal and return the open batches. |
| [List Terminal batches](/api-reference/terminal-batches/list-terminal-batches) | Read persisted batch records, filtered by Terminal, status, or reconciliation status. |
| [Retrieve a Terminal batch](/api-reference/terminal-batches/retrieve-a-terminal-batch) | Read one persisted batch. |
| [List Terminal batch items](/api-reference/terminal-batches/list-terminal-batch-items) | Read the transaction records in a batch's latest snapshot. |
| [List Terminal settlement profiles](/api-reference/terminal-batches/list-terminal-settlement-profiles) | Find the settlement groupings you can filter batches by. |
| [Retrieve a Terminal settlement profile](/api-reference/terminal-batches/retrieve-a-terminal-settlement-profile) | Read one settlement grouping. |

## Statuses

A batch has two status fields.

| Field | Values |
| - | - |
| `status` | `open`, `closing`, `closed` |
| `reconciliation_status` | `not_started`, `pending`, `reconciled`, `incomplete`, `needs_attention` |

Both fields can be used as list filters.

## Rules

* Batch item `operation` is one of `sale`, `refund`, `void`, `reversal`, `authorization`, `ticket`, or `tip_adjustment`.
* Totals (`sales`, `refunds`, `voids`, `tips`, `fees`, `tax`, `net`) are integers in minor currency units. `net` is null when it is not available.
* `closed_at` and `reconciled_at` are null until those events occur.
* Platforms select an authorized connected account with `Ionic-Account`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.