Skip to content
VestiarionDocs

API reference

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 as Authorization: Bearer ….

Parameters

  • limitintegeroptional

    How many items to return. Defaults to 50; a larger value is capped at 200.

    Default:50

    Allowed:1 to 200

  • cursorstringoptional

    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.

  • directionstringoptional

    Only payables, or only receivables.

    Allowed:payablereceivable

  • statusstringoptional

    Only invoices in this status.

    Allowed:pendingmatchedscheduledpaidheldflaggedawaiting_inforeceivedrejected

  • counterpartyIdstringoptional

    Only invoices from or to this counterparty.

Try it

The key is kept in memory only, for this page.

Code samples

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

Response

Example
200 · application/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
  • dataarray of object
    19 fields in data
    • idstring
    • directionstring

      One ofpayablereceivable

    • statusstring
    • amountnumber
    • currencystring

      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.

    • memostring · nullable
    • poReferencestring · nullable
    • goodsReceivedboolean
    • dueDatestring
    • scheduledForstring · nullable

      ISO timestamp the agent has committed to pay this on, once scheduled; else null.

    • earlyPayDiscountobject · nullable

      The early-payment discount this invoice carries, if any: the percent off and the deadline's ISO timestamp.

      2 fields in earlyPayDiscount
      • percentnumber
      • deadlinestring
    • decidedAtstring · nullable
    • settledAtstring · nullable
    • escalatedAtstring · nullable
    • agentReasoningstring · nullable

      Why the agent ruled as it did, verbatim from the decision.

    • txHashstring · nullable

      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.

    • paidAmountnumber · nullable

      What actually left once this invoice was paid; null otherwise, even while a submitted transfer already carries an amount.

    • counterpartyobject · nullable
      3 fields in counterparty
      • idstring
      • namestring
      • riskLevelstring
    • createdAtstring
  • pageobject

    Where this page sits in the collection.

    3 fields in page
    • nextCursorstring · nullable

      Pass back as ?cursor= to continue. Null when the end is reached.

    • hasMoreboolean

      Whether another page follows this one.

    • countinteger

      How many items this response carries.

Errors

StatusCodeWhen
400invalid_requestAn 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.
401unauthorizedNo key, or a malformed, unknown or revoked one: "A valid API key is required."
403forbiddenThe 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."
500internalAn unexpected server error. Implementation details are not exposed.