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

# POST /merchants/{merchantID}/transactions/list

> Query and filter transactions for a merchant using state, date range, token IDs, and invoice IDs. Returns a paginated list of transaction records.

Use this endpoint to search and filter transactions for a merchant account. Unlike a simple list, this endpoint accepts a JSON request body with filter criteria, making it well-suited for building reporting dashboards, reconciliation tools, or transaction exports.

## Path parameters

<ParamField path="merchantID" type="string" required>
  The UUID of the merchant account to query transactions for.
</ParamField>

## Query parameters

<ParamField query="limit" type="number" default="20">
  Maximum number of transactions to return per page.
</ParamField>

<ParamField query="page" type="number" default="1">
  Page number for pagination.
</ParamField>

<ParamField query="order" type="string" default="desc">
  Sort direction. Accepted values: `asc`, `desc`.
</ParamField>

<ParamField query="orderBy" type="string">
  Field to sort results by. Accepted values depend on the `orderByTransactions` enum (e.g., `createdAt`, `amount`).
</ParamField>

## Request body

All filter fields are optional. Omitting a field returns results regardless of that attribute.

<ParamField body="states" type="string[]">
  Filter by transaction state. Example: `["confirmed", "pending"]`.
</ParamField>

<ParamField body="dateFrom" type="string">
  Return only transactions created on or after this ISO 8601 datetime.
</ParamField>

<ParamField body="dateTo" type="string">
  Return only transactions created on or before this ISO 8601 datetime.
</ParamField>

<ParamField body="tokens" type="number[]">
  Filter by payment method (token) ID. Example: `[1, 2]`.
</ParamField>

<ParamField body="invoiceIDs" type="string[]">
  Filter by invoice UUID. Use this to retrieve all transactions for specific invoices.
</ParamField>

## Response

Returns a paginated list of transaction objects.

<ResponseField name="data" type="object[]">
  Array of transaction objects.

  <Expandable title="transaction properties">
    <ResponseField name="id" type="string">
      The UUID of the transaction.
    </ResponseField>

    <ResponseField name="invoiceID" type="string">
      The UUID of the associated invoice.
    </ResponseField>

    <ResponseField name="amount" type="string">
      The transaction amount as a decimal string.
    </ResponseField>

    <ResponseField name="state" type="string">
      The current state of the transaction.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp of when the transaction was created.
    </ResponseField>

    <ResponseField name="confirmedAt" type="string">
      ISO 8601 timestamp of on-chain confirmation, or `null` if pending.
    </ResponseField>

    <ResponseField name="txHash" type="string">
      The on-chain transaction hash, or `null` if not yet broadcast.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="number">
  Total number of transactions matching the applied filters.
</ResponseField>

<ResponseField name="page" type="number">
  The current page number.
</ResponseField>

<ResponseField name="limit" type="number">
  The number of results returned per page.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://api.iterapay.com/merchants/b0fcc813-a7ce-4bbc-932f-dbef6f59ca7f/transactions/list?limit=20&page=1&order=desc' \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
      "states": ["confirmed"],
      "dateFrom": "2024-01-01T00:00:00Z",
      "dateTo": "2024-01-31T23:59:59Z",
      "tokens": [1, 2],
      "invoiceIDs": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "data": [
      {
        "id": "b0fcc813-a7ce-4bbc-932f-dbef6f59ca7f",
        "invoiceID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "amount": "100.00",
        "state": "confirmed",
        "createdAt": "2024-01-15T10:30:00Z",
        "confirmedAt": "2024-01-15T10:35:12Z",
        "txHash": "f4184fc596403b9d638783cf57adfe4c75c605f6356fbc91338530e9831e9e16"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  }
  ```
</ResponseExample>