# List invoices

`GET /api/v1/invoices`

The payable and receivable book, newest first, with the row id breaking equal timestamps. Each invoice carries the agent's reasoning, not only its verdict. Only a transaction reference beginning with `0x` is exposed as `txHash`; a simulated receipt gives `null`.

An unknown `direction` or `status` is refused with `400` rather than ignored.

Send a [workspace API key](https://www.vestiarion.xyz/docs/get-started/authentication) as `Authorization: Bearer <key>`.

## Parameters

| Name | In | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- | --- |
| `limit` | query | integer | Optional | `50` | 1 to 200 | How many items to return. Defaults to 50; a larger value is capped at 200. |
| `cursor` | query | string | Optional | — | — | The previous response's `page.nextCursor`, passed back unchanged to continue. Opaque: never decode or construct one. A cursor this endpoint could not have issued is refused with `400`. |
| `direction` | query | string | Optional | — | `payable`, `receivable` | Only payables, or only receivables. |
| `status` | query | string | Optional | — | `pending`, `matched`, `scheduled`, `paid`, `held`, `flagged`, `awaiting_info`, `received`, `rejected` | Only invoices in this status. |
| `counterpartyId` | query | string | Optional | — | — | Only invoices from or to this counterparty. |

## Code samples

```bash
curl "https://www.vestiarion.xyz/api/v1/invoices" \
  -H "Authorization: Bearer $VESTIARION_API_KEY"
```

## Response

Example, `200` `application/json`:

```json
{
  "data": [
    {
      "id": "9440f32c-000d-4a63-97f1-4eb6bf78439f",
      "direction": "payable",
      "status": "paid",
      "amount": 0.11,
      "currency": "USDC",
      "memo": "Stage-isolation verification",
      "poReference": "PO-4001",
      "goodsReceived": true,
      "dueDate": "2026-09-28T15:22:48.928+00:00",
      "scheduledFor": null,
      "earlyPayDiscount": null,
      "decidedAt": "2026-09-24T15:24:22.75+00:00",
      "settledAt": "2026-09-24T15:24:22.75+00:00",
      "escalatedAt": null,
      "agentReasoning": "Three-way match is complete: PO-4001 is on file and goodsReceived is true. Counterparty Vercel Inc has riskLevel 'clear' (not high) and the invoice amount 0.11 USDC is below the counterparty payment limit of 2 USDC. Treasury operatingBalance is 22.875 USDC, leaving 22.765 USDC after payment, and no duplicate matches were found (duplicateNote confirms no earlier payable from this counterparty resembles this invoice), so there is no fraud indicator.",
      "txHash": "0xda97ba74aca6a45e4759858230e743aac0735252b874fb07c20ec8026d80a7bf",
      "paidAmount": 0.11,
      "counterparty": {
        "id": "4e363b59-d1ca-4425-924c-5c894bc3373f",
        "name": "Vercel Inc",
        "riskLevel": "clear"
      },
      "createdAt": "2026-09-24T15:22:50.176754+00:00"
    }
  ],
  "page": {
    "nextCursor": "eyJrIjoiMjAyNi0wOS0yNFQxNToyMjo1MC4xNzY3NTQrMDA6MDAiLCJpZCI6Ijk0NDBmMzJjLTAwMGQtNGE2My05N2YxLTRlYjZiZjc4NDM5ZiJ9",
    "hasMore": true,
    "count": 1
  }
}
```

**Fields**

- `data` (array of object, required)
  - `id` (string, required)
  - `direction` (string, required) One of `payable`, `receivable`.
  - `status` (string, required)
  - `amount` (number, required)
  - `currency` (string, required): USDC or EURC: what `amount` is in, and what a payable is paid in. A EURC payable is checked against the counterparty's USDC limit at a quoted rate.
  - `memo` (string, nullable, required)
  - `poReference` (string, nullable, required)
  - `goodsReceived` (boolean, required)
  - `dueDate` (string, required)
  - `scheduledFor` (string, nullable, required): ISO timestamp the agent has committed to pay this on, once scheduled; else null.
  - `earlyPayDiscount` (object, nullable, required): The early-payment discount this invoice carries, if any: the percent off and the deadline's ISO timestamp.
    - `percent` (number, required)
    - `deadline` (string, required)
  - `decidedAt` (string, nullable, required)
  - `settledAt` (string, nullable, required)
  - `escalatedAt` (string, nullable, required)
  - `agentReasoning` (string, nullable, required): Why the agent ruled as it did, verbatim from the decision.
  - `txHash` (string, nullable, required): An on-chain hash once the payment settled, else null: on Arc testnet, or for a payout from a Gateway balance the mint on the payee's chain.
  - `paidAmount` (number, nullable, required): What actually left once this invoice was paid; null otherwise, even while a submitted transfer already carries an amount.
  - `counterparty` (object, nullable, required)
    - `id` (string, required)
    - `name` (string, required)
    - `riskLevel` (string, required)
  - `createdAt` (string, required)
- `page` (object, required): Where this page sits in the collection.
  - `nextCursor` (string, nullable, required): Pass back as `?cursor=` to continue. Null when the end is reached.
  - `hasMore` (boolean, required): Whether another page follows this one.
  - `count` (integer, required): How many items this response carries.

## Errors

| Status | Code | When |
| --- | --- | --- |
| 400 | `invalid_request` | An invalid `limit` or `cursor`, a filter value outside its allowed values, or a request body that does not validate. The message names the parameter or the field, and lists the accepted values. |
| 401 | `unauthorized` | No key, or a malformed, unknown or revoked one: "A valid API key is required." |
| 403 | `forbidden` | The key's scopes do not cover this route: "This key cannot do that." Or, on a write, the person who created the key can no longer add records: "This key's issuer can no longer add records in this workspace." |
| 500 | `internal` | An unexpected server error. Implementation details are not exposed. |