Invoice Data Model

This page documents all fields available in the Invoice object, their types, requirements, and usage.

Invoice Object

An invoice is represented as a JSON object with the following structure:

Field	Type	Required	Description	Example
id	`string`	Required	Unique invoice identifier, prefixed with 'inv_'	`inv_01HXYZ...`
organization_id	`string`	Required	ID of the organization that owns this invoice	`org_01HABC...`
external_id	`string \| null`	Optional	External reference ID from your CRM or accounting system	`crm-12345`
number	`string`	Required	Human-readable invoice number, auto-generated if not provided	`INV-2025-0001`
customer_name	`string`	Required	Legal name of the customer	`Acme Ltd`
customer_email	`string \| null`	Optional	Billing email address for the customer	`[email protected]`
customer_wallet	`string \| null`	Optional	Wallet address or payment identifier (e.g., Lightning invoice)	`lnbc1... or 0x...`
amount	`number (Decimal)`	Required	Invoice amount, must be positive	`120.00`
currency	`string`	Required	ISO currency code (USD, EUR, SAT, BTC, etc.)	`USD`
status	`enum`	Required	Current status of the invoice	`sent`
issued_at	`datetime`	Required	When the invoice was issued (ISO 8601 UTC)	`2025-11-24T10:00:00Z`
due_at	`datetime \| null`	Optional	When the invoice is due (ISO 8601 UTC)	`2025-12-01T10:00:00Z`
paid_at	`datetime \| null`	Optional	When payment was recorded (ISO 8601 UTC)	`2025-11-25T10:00:00Z`
source	`string`	Required	How the invoice was created (api, agent, dashboard, etc.)	`api`
created_at	`datetime`	Required	Creation timestamp (ISO 8601 UTC)	`2025-11-24T10:00:00Z`
updated_at	`datetime`	Required	Last update timestamp (ISO 8601 UTC)	`2025-11-24T10:00:00Z`

Status Enum Values

The status field accepts one of the following values:

draft - Invoice is created but not sent
sent - Invoice has been sent to the customer
paid - Payment has been received
overdue - Invoice has passed its due date
canceled - Invoice has been canceled

Datetime Format

All datetime fields use ISO 8601 format in UTC. Examples:

2025-11-24T10:00:00Z
2025-11-24T10:00:00+00:00

When creating invoices, you can omit the timezone (it will default to UTC) or explicitly specify UTC with Z suffix.

Organization Scoping

All invoices are scoped to an organization via organization_id. This is automatically set based on:

API Key Context: When using API keys, the organization is derived from the key
User Session: When using the dashboard, the organization is from the user's active organization

Row-level security (RLS) policies ensure users can only access invoices from their organization.

Example Invoice Object