---
title: "Add an invoice"
method: POST
path: "/api/v1/invoices"
tags: ["Payables and receivables"]
---

# Add an invoice

`POST /api/v1/invoices`

## Request

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

Adds a payable or a receivable, checked by the rules of the console's invoice form, and recorded in the ledger as `create_invoice` with `via: "api"` and the key's id. It is added as the key's issuer's: if the agent holds it, the issuer cannot approve it, unless they are the workspace's only approver.

The agent decides a payable as one typed in, with every guardrail and the workspace's limits, usually within a minute. The API never approves or pays. A `counterpartyId` the workspace does not hold, including another workspace's, answers `400`.

## Headers

- `Idempotency-Key` string

## Request body

- CreateInvoiceRequest: An invoice to add. The agent decides a payable as one typed in, with every guardrail, usually within a minute.
  - `direction` 'payable' | 'receivable': `payable`, a bill the business pays, which is the default, or `receivable`, one it is owed.
  - `counterpartyId` string, required: The counterparty's `id`, from `GET /api/v1/counterparties` or from the answer that added it.
  - `amount` union, required: What it bills, in `currency`, with at most 6 decimal places. A decimal string such as `"1250.50"` keeps it exact; a number is read the same way.
    - string
    - number
  - `currency` 'USDC' | 'EURC': `USDC`, the default, or `EURC`.
  - `dueDate` string, required: The day it is due, as `YYYY-MM-DD`.
  - `memo` string: What it is for, up to 280 characters.
  - `poReference` string: The purchase order it bills against, up to 100 characters.
  - `goodsReceived` boolean: Whether what it bills for has arrived. Defaults to `false`. Without it, or without `poReference`, the agent asks for the missing detail instead of paying.
  - `earlyPayDiscount` object: A discount for paying by `deadline`. The agent weighs it against what the cash would earn in the reserve until `dueDate`.
    - `percent` union, required: The percent off, greater than 0 and less than 100, with at most 2 decimal places.
      - string
      - number
    - `deadline` string, required: The last day it applies, as `YYYY-MM-DD`, on or before `dueDate`.

## Response `201`

Created

- CreateInvoiceResponse
  - `data` object, required: An invoice in the payable or receivable book, with the agent's reasoning.
    - `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

## Other responses

- `400`: invalid_request
- `401`: unauthorized
- `403`: forbidden
- `409`: conflict
- `429`: rate_limited
- `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)