> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nextoriahub.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoices API

> Create, send, and manage invoices via the Nextoria Hub REST API.

## Endpoints

| Method  | Path                    | Description             |
| ------- | ----------------------- | ----------------------- |
| `GET`   | `/v1/invoices`          | List invoices           |
| `POST`  | `/v1/invoices`          | Create an invoice       |
| `GET`   | `/v1/invoices/:id`      | Get an invoice          |
| `PATCH` | `/v1/invoices/:id`      | Update a draft invoice  |
| `POST`  | `/v1/invoices/:id/send` | Send invoice to client  |
| `POST`  | `/v1/invoices/:id/void` | Void an invoice         |
| `GET`   | `/v1/invoices/:id/pdf`  | Download invoice as PDF |

***

## List Invoices

```bash theme={null}
GET /v1/invoices
```

**Query Parameters:**

| Parameter    | Type   | Description                                |
| ------------ | ------ | ------------------------------------------ |
| `status`     | string | `draft`, `sent`, `paid`, `overdue`, `void` |
| `client_id`  | string | Filter by client                           |
| `project_id` | string | Filter by project                          |
| `from`       | string | ISO date — filter by issue date (start)    |
| `to`         | string | ISO date — filter by issue date (end)      |

**Example Response:**

```json theme={null}
{
  "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
  }
}
```

***

## Create an Invoice

```bash theme={null}
POST /v1/invoices
```

**Request Body:**

```json theme={null}
{
  "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!"
}
```

**Response:** `201 Created` with the invoice object.

***

## Send an Invoice

```bash theme={null}
POST /v1/invoices/:id/send
```

Transitions the invoice from `draft` to `sent` and emails the client a payment link.

**Request Body (optional):**

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

**Response:**

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

***

## Invoice Object

```typescript theme={null}
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;
}
```

<Info>
  All monetary values are returned in **minor currency units** (e.g. cents for
  USD). A `total` of `13200` represents `$132.00` USD.
</Info>