---
title: "List invoices"
method: GET
path: "/api/v1/invoices"
tags: ["Payables and receivables"]
---

# List invoices

`GET /api/v1/invoices`

## Request

- Base URL: `https://www.vestiarion.xyz`
- URL: `https://www.vestiarion.xyz/api/v1/invoices`
- Auth: HTTP bearer

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.

## Query parameters

- `limit` integer
- `cursor` string
- `direction` 'payable' | 'receivable'
- `status` 'pending' | 'matched' | 'scheduled' | 'paid' | 'held' | 'flagged' | 'awaiting_info' | 'received' | 'rejected'
- `counterpartyId` string

## Response `200`

OK

- ListInvoicesResponse
  - `data` object[], required
    - `id` string, required
    - `direction` 'payable' | 'receivable', required
    - `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 the workspace's network, 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.

## Other responses

- `400`: invalid_request
- `401`: unauthorized
- `403`: forbidden
- `500`: internal

---

[API](https://skmtc.dev/vestiarion/apis/vestiarion-api.md) · [All operations](https://skmtc.dev/vestiarion/apis/vestiarion-api/llms.txt) · [OpenAPI document](https://skmtc.dev/vestiarion/apis/vestiarion-api/revisions/fd2f589dac9b?raw)