Create & Send Invoices

Create invoices programmatically using the Orvion API. Invoices can be created in draft status and sent later, or created directly in sent status.

Endpoint

POST

/api/v1/invoices

Request Body

Field	Type	Required	Description	Example
external_id	`string \| null`	Optional	External reference ID from your system	`crm-12345`
customer_name	`string`	Required	Legal name of the customer	`Acme Ltd`
customer_email	`string \| null`	Optional	Billing email address	`[email protected]`
customer_wallet	`string \| null`	Optional	Wallet address or payment identifier	`lnbc1...`
amount	`number (Decimal)`	Required	Invoice amount, must be positive	`120.00`
currency	`string`	Required	ISO currency code	`USD`
issued_at	`datetime \| null`	Optional	Invoice issue date (defaults to now)	`2025-11-24T10:00:00Z`
due_at	`datetime \| null`	Optional	Invoice due date	`2025-12-01T10:00:00Z`
status	`enum`	Optional	Invoice status: 'draft' or 'sent' (defaults to 'draft')	`sent`

Status Options

draft (default) - Invoice is created but not sent to the customer
sent - Invoice is immediately sent (if email/webhook configured)

Auto-Generated Fields

The following fields are automatically generated if not provided:

number - Human-readable invoice number (e.g., INV-2025-0001)
issued_at - Current timestamp if not provided
organization_id - Derived from your API key context

Code Examples

import requests
from datetime import datetime

url = "http://localhost:8000/api/v1/invoices"
headers = {
  "Authorization": "Bearer your-api-key",
  "Content-Type": "application/json"
}

data = {
  "external_id": "crm-12345",
  "customer_name": "Acme Ltd",
  "customer_email": "[email protected]",
  "customer_wallet": "lnbc1u1p3xyz...",
  "amount": 120.0,
  "currency": "EUR",
  "issued_at": "2025-11-24T10:00:00Z",
  "due_at": "2025-12-01T10:00:00Z",
  "status": "sent"
}

response = requests.post(url, json=data, headers=headers)
invoice = response.json()
print(invoice)

Response

Returns the complete invoice object with all fields populated:

{
  "id": "inv_01HXYZ123ABC",
  "organization_id": "org_01HABC456DEF",
  "external_id": "crm-12345",
  "number": "INV-2025-0001",
  "customer_name": "Acme Ltd",
  "customer_email": "[email protected]",
  "customer_wallet": "lnbc1u1p3xyz...",
  "amount": 120.0,
  "currency": "EUR",
  "status": "sent",
  "issued_at": "2025-11-24T10:00:00Z",
  "due_at": "2025-12-01T10:00:00Z",
  "paid_at": null,
  "source": "api",
  "created_at": "2025-11-24T10:00:00Z",
  "updated_at": "2025-11-24T10:00:00Z"
}

Error Scenarios

400 Bad Request

Invalid amount (negative or zero)
Invalid currency format
Invalid status value (must be 'draft' or 'sent')
Invalid datetime format for issued_at or due_at

401 Unauthorized

Missing or invalid API key
API key does not have permission to create invoices

422 Unprocessable Entity

Missing required fields (customer_name, amount, currency)
Validation errors (e.g., email format, amount precision)

Idempotency

The create endpoint supports idempotency through the external_id field. If you provide the same external_id for the same organization, the system will update the existing invoice rather than creating a duplicate.