# 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.27
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)

## 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 (e.g. `open`, `closed`, `settled`).

  - `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 in dollars (approved minus refunds and voids).  Amount in cents (e.g. `10000` = $100.00). All transactions are in  US dollars (USD).

  - `results.approved_amount` (integer, required)
    Total approved transaction amount in dollars. 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 dollars. 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 dollars. 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 dollars. 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)
    Human-readable form of `closed_at`, in the gateway's local time with no offset. Null while the batch is still open. Twelve-hour clock — prefer `closed_at`, which is ISO 8601 and unambiguous.

  - `results.settled_at_date_time` (string | null, required)
    Human-readable form of `settled_at`, in the gateway's local time with no offset. Null until the batch settles. Twelve-hour clock — prefer `settled_at`, which is ISO 8601 and unambiguous.

  - `results.created_at_date_time` (string, required)
    Human-readable form of `created_at`, in the gateway's local time with no offset. Twelve-hour clock — prefer `created_at`, which is ISO 8601 and unambiguous.

  - `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)

## Response 401 examples:

  - `Missing or invalid API key` (unknown)

## Response 403 examples:

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

## Response 500 examples:

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