Invoices

Every confirmed payment, checkout or subscription renewal, issues a tax-compliant invoice: buyer details, applied tax rate and amount, exchange rate at settlement, and the merchant record AgentaOS billed as. agentaos.invoices reads those records and downloads their documents. There’s no create, invoices are generated by AgentaOS when a payment confirms.

`invoices.list(params?)`

const page = await agentaos.invoices.list({
  from: '2026-03-01',
  to: '2026-03-31',
  status: 'issued',
  limit: 50,
});

string

ISO 8601 date, inclusive lower bound.

string

ISO 8601 date, inclusive upper bound.

'all' | 'issued' | 'paid' | 'voided'

number

default:"20"

Max 5000.

number

default:"0"

Returns PaginatedList<Invoice>.

Invoice fields

string

string | null

string

e.g. 'INV-2026-0001'.

number

Currency units, in paymentToken.

string

The token the buyer paid with, e.g. 'EURC'.

string | null

On-chain settlement transaction, if applicable.

string

number | null

EUR/USD equivalent, currency units.

string | null

'EUR' or 'USD'.

number | null

Rate applied at settlement.

string | null

ISO 8601.

string | null

string

number | null

e.g. 19 for 19%.

number | null

Currency units.

boolean | null

string | null

e.g. 'DE VAT'.

string | null

ISO 3166-1 alpha-2.

string | null

'issued' | 'paid' | 'voided'

string

ISO 8601.

string | null

ISO 8601.

string

ISO 8601.

amount, fiatAmount, and taxAmount are plain decimal currency-unit numbers, not minor units. 19.99 means €19.99. See the money model.

`invoices.retrieve(id)`

const invoice = await agentaos.invoices.retrieve('uuid');

Returns the full Invoice shape above for a single record.

`invoices.void(id)`

await agentaos.invoices.void('uuid');
// → { success: true }

Sets status to 'voided' and stamps voidedAt. The record is retained, retrieve() still returns it.

Downloads

Every download method returns raw bytes, not a parsed JSON object. PDFs come back as Buffer, the CSV export comes back as string.

const pdf = await agentaos.invoices.downloadPdf('uuid'); // Promise<Buffer>
fs.writeFileSync('invoice.pdf', pdf);

// Monthly statement PDF: balance reconciliation, VAT summary, transaction ledger.
const statement = await agentaos.invoices.downloadStatement({
  from: '2026-03-01',
  to: '2026-03-31',
}); // Promise<Buffer>
fs.writeFileSync('march-statement.pdf', statement);

const csv = await agentaos.invoices.exportCsv({
  from: '2026-03-01',
  to: '2026-03-31',
  status: 'issued',
}); // Promise<string>
fs.writeFileSync('invoices.csv', csv);

// Receipt PDF for a paid invoice. Falls back to the invoice PDF for
// invoices issued before receipts existed.
const receipt = await agentaos.invoices.getReceipt('uuid'); // Promise<Buffer>
fs.writeFileSync('receipt.pdf', receipt);

string

required

ISO 8601 date. Required for downloadStatement, optional for exportCsv.

string

required

ISO 8601 date. Required for downloadStatement, optional for exportCsv.

string

exportCsv only, optional.

exportCsv’s params are all optional: { from?: string; to?: string; status?: string }. downloadStatement requires both from and to.

`invoices.sendReceipt(id)`

Re-sends the receipt email to the buyer on file. Paid invoices only.

const result = await agentaos.invoices.sendReceipt('uuid');
console.log(result.sentTo); // buyer email the receipt was sent to

true

string

The email address the receipt was sent to.

Next steps

Checkouts

invoiceId/invoiceNumber on a completed checkout point back here.

Customers

The buyers these invoices are billed to.

Errors

What a missing or already-actioned invoice ID throws.

SDK

CLI

API Reference

`invoices.list(params?)`

Invoice fields

`invoices.retrieve(id)`

`invoices.void(id)`

Downloads

`invoices.sendReceipt(id)`

Next steps

Checkouts

Customers

Errors

​invoices.list(params?)

​Invoice fields

​invoices.retrieve(id)

​invoices.void(id)

​Downloads

​invoices.sendReceipt(id)

​Next steps

Checkouts

Customers

Errors

`invoices.list(params?)`

Invoice fields

`invoices.retrieve(id)`

`invoices.void(id)`

Downloads

`invoices.sendReceipt(id)`

Next steps