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

# Lists, Pagination and Filters

> Page through a list with a cursor, and filter it with query parameters

A list returns an array of one representation in `result`, with `pagination` beside it. Each list's reference says how it's ordered, which is normally newest first, and which filters it takes.

```json theme={null}
{
  "result": [
    {
      "_type": "payout",
      "_uri": "/payouts/po_1",
      "_view": "full",
      "id": "po_1",
      "status": "sent",
      "...": "..."
    }
  ],
  "entities": {},
  "not_included": [],
  "pagination": { "type": "cursor", "limit": 25, "next_cursor": "c2Vjb25k", "has_more": true }
}
```

The resource above is shortened.

## Cursor Pagination

A list takes `limit` and `cursor`. `limit` defaults to 25, with a maximum of 100, unless the list documents otherwise.

1. Ask for the first page with no `cursor`.
2. While `has_more` is `true`, ask for the next page with `cursor` set to `next_cursor`, and the same filters.
3. On the last page, `has_more` is `false` and `next_cursor` is `null`.

```bash theme={null}
curl 'https://api.quidkey.com/v1/merchants/m_1/transactions?status=completed&limit=50&cursor=c2Vjb25k' \
  -H 'Authorization: Bearer ACCESS_TOKEN'
```

* A cursor is opaque. Don't parse it or build one.
* A cursor is only valid with the filters it was issued for. Keep them the same from page to page.
* A page can hold fewer than `limit` items, so rely on `has_more`, not on the page's length.

## Filtering

Filter on a field by naming it. `&` always means AND, and comma-separated values within one field mean OR.

```txt theme={null}
?status=completed,pending&payment_link_id=pl_1
```

That matches a status of `completed` or `pending`, with the payment link `pl_1`.

* **Values with commas.** A value containing a comma or a double quote is wrapped in double quotes, with a double quote inside it doubled, as in CSV: `?order_id="Smith, Jones",Acme` matches `Smith, Jones` or `Acme`.

* **Encoding.** Percent-encoding makes no difference: `completed,pending` and `completed%2Cpending` mean the same, as do `created_at:gte` and `created_at%3Agte`.

* **One of each.** A repeated parameter, such as `?status=completed&status=pending`, answers 400.

* **Ranges.** A range adds an operator after a colon, one of `:gte`, `:gt`, `:lte` and `:lt`, and takes one value:

  ```txt theme={null}
  ?created_at:gte=2026-11-01T00:00:00.000Z&created_at:lt=2026-12-01T00:00:00.000Z
  ```

* **Money ranges.** An amount range gives the value in minor units, with its currency beside it: `?amount:gte=10000&currency=GBP`. A money range without `currency` answers 400.

* **Unknown filters** answer 400, so a typo never silently returns everything.

* **Values** match the values the resource returns, such as `?type=refund`.

An unfiltered list returns everything you can read, unless it documents otherwise. Transactions and payment links are the exception: a list holds live records, and `?is_test=true` lists test ones instead.

## Searching

A search too complex for a query string, or one carrying personal data, uses a `:search` action with a JSON body. It takes the list's filters in the body, and answers as the list does, in the same order. `limit` and `cursor` stay in the query string.

```bash theme={null}
curl -X POST 'https://api.quidkey.com/v1/merchants/m_1/transactions:search?limit=25' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": ["payment"],
    "status": ["completed"],
    "created_at": { "gte": "2026-11-01T00:00:00.000Z", "lt": "2026-12-01T00:00:00.000Z" },
    "customer_email": "customer@example.com"
  }'
```

In the body, a filter that takes several values takes an array, and a range is an object of its operators, such as `"created_at": { "gte": …, "lt": … }`. A money range names one currency beside it: `"amount": { "gte": 1000 }, "currency": ["GBP"]`.

`POST /merchants/{id}/transactions:search` adds `q`, a contains match on the order ID, the transaction number and the customer's name and email, and `customer_email`, an exact match. Neither belongs in a URL, where it would be logged.

## Files

`GET /merchants/{id}/transactions` and `POST /merchants/{id}/transactions:search` also answer a file, for an accounting tool or a spreadsheet. Ask for one with `Accept`:

| `Accept` | File |
| - | - |
| `text/csv` | CSV as RFC 4180 defines it, in UTF-8 with a header row |
| `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` | An Excel workbook of one sheet with a header row, each amount a number and every other cell text |

```bash theme={null}
curl 'https://api.quidkey.com/v1/merchants/m_1/transactions?status=completed' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Accept: text/csv' \
  -o transactions.csv
```

* **The whole result.** A file holds every record the filters match, in the list's order. It isn't paged, so `limit`, `cursor` or `include` with a file answers 400.
* **At most 10,000 rows.** A result with more answers 422 `EXPORT_TOO_LARGE`, never a shorter file. Its detail names `Accept` and gives the limit. Narrow the filters, such as with `created_at` or `payout_id`, and ask again.
* **The same request.** A file takes the list's filters, or the search's body, and holds the records the JSON would. It takes the list's permission and the single read's, such as `transactions:get`, since each row is a full representation. An empty result is a file with only the header row.
* **The full representation.** Each row is one record's full representation, flattened, with its amounts as decimals: [Transaction export](https://docs.quidkey.com/api-v1/reference/transaction-export.md) lists the columns.
* A file comes as an attachment, with `Cache-Control: no-store`. A request that fails answers an error, never part of a file.

With no `Accept`, or with `application/json`, a list answers JSON. A format the endpoint doesn't offer answers 406.

## Totals

A list doesn't return totals, so listing stays cheap. To total a merchant's balance in one currency, see [Reconcile payouts](https://docs.quidkey.com/api-v1/journeys/reconcile.md).


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