API Invoices Endpoint

Invoices API

Base path: /api/v1/invoices. Auth scope: invoices.read, invoices.create, invoices.update.

GET /api/v1/invoices

List invoices. Query params: page, per_page, client_id, status (unpaid, paid, overdue, cancelled).

GET /api/v1/invoices/{id}

Get invoice with items.

POST /api/v1/invoices

Create invoice. Required: client_id, items (array of {description, quantity, price}). Optional: tax.

{
  "client_id": 1,
  "items": [
    {"description": "Hosting - Monthly", "quantity": 1, "price": 9.99}
  ],
  "tax": 0
}

Response 201: {"success":true,"data":{"id":1,"uuid":"...","invoice_number":"INV-000001"},"message":"Invoice created"}

POST /api/v1/invoices/{id}/pay

Record payment. Body: amount (default: invoice total), payment_method (default: manual).

Validation: Returns ALREADY_PAID (400) if invoice already paid.

Idempotency: Not idempotent. Calling twice will create two transactions. Do not double-submit.