Finance API

REST endpoints for the Finance module — invoices, payments, expenses, recurring templates, payment links.

Endpoints

Method	Path	Purpose
GET	`/api/finance/invoices`	List. Filters: `status`, `contact_id`, `company_id`, date range.
POST	`/api/finance/invoices`	Create.
GET/PATCH/DELETE	`/api/finance/invoices/{id}`	CRUD.
POST	`/api/finance/invoices/{id}/send`	Email invoice to the linked contact. Flips status → `sent`.
GET	`/api/finance/invoices/{id}/payment-link`	Current Stripe Checkout URL (if any).
POST	`/api/finance/invoices/{id}/payment-link`	Create or return existing Stripe Checkout Session. Idempotent. Requires `finance.invoices.update`.
GET	`/api/finance/invoices/{id}/pdf`	Render a printable HTML PDF.
GET	`/api/finance/payments`	List payments.
POST	`/api/finance/payments`	Manually record a payment.
GET	`/api/finance/expenses`	List expenses.
POST	`/api/finance/expenses`	Create.
GET	`/api/finance/recurring-invoices`	List active recurring templates.
POST	`/api/finance/recurring-invoices`	Create.
PATCH	`/api/finance/recurring-invoices/{id}`	Update (e.g. pause, change frequency).

Key entity shapes

Invoice

{
  "id": "uuid",
  "tenant_id": "uuid",
  "invoice_number": "INV-202606-0001",
  "status": "draft | sent | overdue | paid",
  "contact_id": "uuid?",
  "company_id": "uuid?",
  "issue_date": "iso-8601",
  "due_date": "iso-8601",
  "total": 0,
  "currency": "USD",
  "stripe_payment_link_url": "string?",
  "paid_at": "iso-8601?"
}

Payment

{
  "id": "uuid",
  "tenant_id": "uuid",
  "invoice_id": "uuid",
  "amount": 0,
  "currency": "USD",
  "payment_method": "credit_card | bank_transfer | cash | other",
  "payment_date": "iso-8601",
  "stripe_session_id": "string?"
}

Permissions

Seeded slugs:

finance.invoices.read|create|update|delete|send
finance.payments.read|create
finance.expenses.read|create|update|delete|approve
finance.export (read-only export of all financial data)

The payment-link creation route specifically requires finance.invoices.update (operator-only).

Events

finance.invoice.created|updated|sent|paid|overdue|deleted
finance.payment.received
finance.expense.created|updated|approved|deleted

Webhooks (inbound)

POST /api/webhooks/stripe — Stripe checkout.session.completed. Verifies signature, writes a payments row, marks invoice paid.

OpenAPI

Full schema at /api/openapi.json.