# List Batches

Return a list of batches. Use the query parameters to filter and sort  the results.

Endpoint: GET /v1/batches
Version: 1.0.0-beta.54
Security: ApiKeyAuth

## Security:

  - `ApiKeyAuth` (unknown)
    apiKey in header Api-Key

## Query parameters:

  - `skip` (string)

  - `take` (string)

  - `sort_column` (string)

  - `sort_order` (string)

  - `search_text` (string)

  - `term` (string)
    Filters the batch list. A comma-separated list of pieces, each one of: a `createdate` comparison against a quoted ISO 8601 timestamp, using `>=`, `<=`, `>`, `<` or `=` and repeatable to bound a range; one `status=` with `opened`, `closed`, `in_progress` or `failed`; and one IANA time zone name or `UTC`. 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 omitted. A `term` holding any other piece is refused, and the response today is 500 `SYSTEM_ERROR` rather than 400.

## Header parameters:

  - `Client-Id` (string, required)

  - `X-Acting-As-Client-Id` (string)
    The child client this request acts on behalf of. A reseller still authenticates as itself — `Api-Key` and `Client-Id` stay the reseller's — and names the child here.
This works only from a parent to its own children. Merchants have no children, so a merchant calling as itself omits the header. Sending your own client ULID here is not the same as omitting it, and is rejected on some operations.

## Response 200:

  - `200` (unknown)
    Batch list returned successfully

## Response 200 fields (application/json):

  - `count` (integer, required)
    Total number of batch records matching the query.

  - `results` (array, required)
    List of batch records.

  - `results.id` (string, required)
    Unique identifier for the batch assigned by the API server.

  - `results.processor` (string | null, required)
    The payment processor that processed this batch. Null when the processor is unknown or not assigned.

  - `results.status` (string, required)
    Current status of the batch, by name. `GET /v1/batches/status` reports the same statuses as numeric codes instead: `"2"` closed, `"5"` failed and `"10"` in progress.
    Enum: "Opened", "Closed", "In-Progress", "Failed"

  - `results.client_id` (string, required)
    Unique identifier of the client that owns this batch.

  - `results.closed_at` (string | null)
    ISO 8601 timestamp of when the batch was closed. Null if still open.

  - `results.settled_at` (string | null)
    ISO 8601 timestamp of when the batch was settled. Null if not yet settled.

  - `results.created_at` (string, required)
    ISO 8601 timestamp of when the batch was created.

  - `results.client_dba` (string, required)
    Doing Business As (DBA) name of the client.

  - `results.net_amount` (integer, required)
    Net batch amount (approved minus refunds and voids), in cents (e.g. `10000` = $100.00). All transactions are in US dollars (USD).

  - `results.approved_amount` (integer, required)
    Total approved transaction amount, in cents (e.g. `10000` = $100.00). All transactions are in US dollars (USD).

  - `results.captured_amount` (integer, required)
    Total captured transaction amount, in cents (e.g. `10000` = $100.00). All transactions are in US dollars (USD).

  - `results.void_amount` (integer, required)
    Total voided transaction amount, in cents (e.g. `10000` = $100.00). All transactions are in US dollars (USD).

  - `results.refund_amount` (integer, required)
    Total refunded transaction amount, in cents (e.g. `10000` = $100.00). All transactions are in US dollars (USD).

  - `results.request` (string | null, required)
    Raw request payload sent to the processor for batch close. Null when not available.

  - `results.response` (string | null, required)
    Raw response payload received from the processor. Null when not available.

  - `results.batch_number` (integer, required)
    Sequential batch number assigned by the processor.

  - `results.batch_type` (string, required)
    The type of batch (e.g. `Credit` or `Debit`).

  - `results.batch_id` (string, required)
    Unique batch identifier assigned by the API server.

  - `results.closed_at_date_time` (string | null, required)
    Deprecated, and removed on or after 2026-12-01. Read `closed_at` instead, which is ISO 8601 and unambiguous. Human-readable form of `closed_at`, in the gateway's local time with no offset and on a twelve-hour clock. Null while the batch is still open.

  - `results.settled_at_date_time` (string | null, required)
    Deprecated, and removed on or after 2026-12-01. Read `settled_at` instead, which is ISO 8601 and unambiguous. Human-readable form of `settled_at`, in the gateway's local time with no offset and on a twelve-hour clock. Null until the batch settles.

  - `results.created_at_date_time` (string, required)
    Deprecated, and removed on or after 2026-12-01. Read `created_at` instead, which is ISO 8601 and unambiguous. Human-readable form of `created_at`, in the gateway's local time with no offset and on a twelve-hour clock.

  - `results.batch_net_deposit` (integer | null)
    Net amount deposited for the batch, in cents (e.g. `10000` = $100.00). Null until the processor reports it.

  - `correlation_id` (string)
    Identifier the gateway assigns to the request and carries across the services that handled it. Quote it when reporting a problem.

## Response 200 headers (application/json):

  - `x-request-id` (string, required)
    Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced.

## Response 400:

  - `400` (unknown)
    Bad request

## Response 400 fields (application/json):

  - `error_code` (string)
    The Gateway generated error code.

  - `error_message` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `details` (object | null)
    The field in the request that caused the error. May be null  if not applicable.

  - `source` (object | null)
    Object containing host-processor-specific error information.  May be null if not applicable.

  - `source.system` (string | null)
    The host processor name.

  - `source.code` (string | null)
    The host processor code.

  - `source.message` (string | null)
    The host processor message.

## Response 400 headers (application/json):

  - `x-request-id` (string, required)
    Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced.

## Response 401:

  - `401` (unknown)
    Not authenticated

## Response 401 fields (application/json):

  - `error_code` (string)
    The Gateway generated error code.

  - `error_message` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `details` (object | null)
    The field in the request that caused the error. May be null  if not applicable.

  - `source` (object | null)
    Object containing host-processor-specific error information.  May be null if not applicable.

  - `source.system` (string | null)
    The host processor name.

  - `source.code` (string | null)
    The host processor code.

  - `source.message` (string | null)
    The host processor message.

## Response 401 headers (application/json):

  - `x-request-id` (string, required)
    Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced.

## Response 403:

  - `403` (unknown)
    Forbidden

## Response 403 fields (application/json):

  - `error_code` (string)
    The Gateway generated error code.

  - `error_message` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `details` (object | null)
    The field in the request that caused the error. May be null  if not applicable.

  - `source` (object | null)
    Object containing host-processor-specific error information.  May be null if not applicable.

  - `source.system` (string | null)
    The host processor name.

  - `source.code` (string | null)
    The host processor code.

  - `source.message` (string | null)
    The host processor message.

## Response 403 headers (application/json):

  - `x-request-id` (string, required)
    Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced.

## Response 500:

  - `500` (unknown)
    Internal server error

## Response 500 fields (application/json):

  - `error_code` (string)
    The Gateway generated error code.

  - `error_message` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `details` (object | null)
    The field in the request that caused the error. May be null  if not applicable.

  - `source` (object | null)
    Object containing host-processor-specific error information.  May be null if not applicable.

  - `source.system` (string | null)
    The host processor name.

  - `source.code` (string | null)
    The host processor code.

  - `source.message` (string | null)
    The host processor message.

## Response 500 headers (application/json):

  - `x-request-id` (string, required)
    Unique identifier assigned to the request by the API server. Returned on every response, including errors. Log this value and supply it when contacting support so that a specific request can be traced.

## Response 400 examples:

  - `Invalid field value in the request body` (unknown)

  - `A required field is absent` (unknown)

  - `The transaction's state does not allow this operation` (unknown)

  - `A single amount is outside the allowed range` (unknown)

  - `A count or dollar cap over a period is spent` (unknown)
    details names the limit: limit_type is COUNT or AMOUNT, window is DAILY or MONTHLY, and scope is ACCOUNT, one payer's bank account, or MERCHANT, everything the merchant submits. A key whose value is not known is left out. No limit figure or reset time is sent.

## Response 401 examples:

  - `Missing or invalid API key` (unknown)

## Response 403 examples:

  - `Authenticated but not authorized for this action` (unknown)

  - `The merchant is not boarded to the processor this transaction routes to` (unknown)
    A card transaction routes to TSYS and an ACH transaction to VeriCheck. Both details keys are always present. The condition lasts until the merchant is boarded, so retrying does not help.

## Response 500 examples:

  - `Unhandled server fault or downstream processor error` (unknown)

  - `The merchant's stored integration record is wrong` (unknown)
    The processor rejected an identifier that came from boarding, not from the request. Retrying does not help until the integration is corrected.

