Invoices API

GET /v1/invoices

{
  "data": [
    {
      "id": "inv_abc123",
      "number": "INV-0042",
      "status": "sent",
      "client": {
        "id": "client_xyz789",
        "name": "Acme Corp"
      },
      "issue_date": "2026-02-01",
      "due_date": "2026-03-01",
      "subtotal": 12000,
      "tax": 1200,
      "total": 13200,
      "amount_paid": 0,
      "currency": "USD",
      "created_at": "2026-01-30T09:00:00Z"
    }
  ],
  "meta": {
    "total": 156,
    "total_outstanding": 37500,
    "total_collected_ytd": 280000
  }
}

POST /v1/invoices

{
  "client_id": "client_xyz789",
  "project_id": "proj_abc123",
  "issue_date": "2026-03-01",
  "due_date": "2026-03-31",
  "currency": "USD",
  "line_items": [
    {
      "description": "Brand Identity Design",
      "quantity": 1,
      "unit_price": 3500
    },
    {
      "description": "Brand Guidelines PDF",
      "quantity": 1,
      "unit_price": 500
    }
  ],
  "tax_rate": 0.1,
  "notes": "Payment due within 30 days. Thank you for your business!"
}

POST /v1/invoices/:id/send

{
  "message": "Hi Jane, please find your invoice for the brand refresh project. Let us know if you have any questions!"
}

{
  "id": "inv_abc123",
  "status": "sent",
  "sent_at": "2026-03-01T10:00:00Z",
  "sent_to": "jane@globexcorp.com"
}

interface Invoice {
  id: string; // "inv_abc123"
  number: string; // "INV-0042"
  status: "draft" | "sent" | "paid" | "overdue" | "void";
  client: { id: string; name: string; email: string };
  project: { id: string; name: string } | null;
  issue_date: string;
  due_date: string;
  currency: string; // ISO 4217 (e.g. "USD", "EUR")
  line_items: LineItem[];
  subtotal: number; // In minor currency units (cents)
  tax_rate: number | null;
  tax: number;
  discount: number;
  total: number;
  amount_paid: number;
  notes: string | null;
  stripe_payment_url: string | null;
  paid_at: string | null;
  created_at: string;
  updated_at: string;
}

interface LineItem {
  description: string;
  quantity: number;
  unit_price: number; // In minor currency units
  total: number;
}