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

# Create Invoice

> Creates a new invoice for a client. The invoice number is auto-generated.

### Headers

<ParamField header="Authorization" type="string" required>
  `Bearer YOUR_API_KEY`
</ParamField>

### Body

<ParamField body="client_id" type="string" required>
  UUID of the client to invoice. Must belong to your account.
</ParamField>

<ParamField body="amount" type="number" required>
  Total invoice amount (must be ≥ 0). If `line_items` are provided and `amount` is omitted, it is calculated automatically.
</ParamField>

<ParamField body="due_date" type="string" required>
  Due date in `YYYY-MM-DD` format.
</ParamField>

<ParamField body="project_id" type="string">
  Optional UUID of an associated project.
</ParamField>

<ParamField body="description" type="string">
  A short description or memo for the invoice.
</ParamField>

<ParamField body="currency" type="string">
  3-letter currency code. Defaults to `USD`.
</ParamField>

<ParamField body="tax_rate" type="number">
  Tax rate as a percentage (0–100). Defaults to `0`.
</ParamField>

<ParamField body="status" type="string">
  Initial status. Either `Draft` (default) or `Sent`.
</ParamField>

<ParamField body="line_items" type="array">
  Optional array of line items. When provided, the total is summed automatically.

  <Expandable title="Line item object">
    <ParamField body="description" type="string" required>Line item label</ParamField>
    <ParamField body="quantity" type="number" required>Quantity</ParamField>
    <ParamField body="rate" type="number" required>Unit price</ParamField>
    <ParamField body="discount" type="number">Discount percentage (0–100). Defaults to `0`.</ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="success" type="boolean">`true` on creation.</ResponseField>

<ResponseField name="data" type="object">
  The newly created invoice, including an embedded `client` object.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://kliio.app/api/v1/invoices \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "client_id": "c1d2e3f4-...",
      "amount": 2000,
      "due_date": "2025-05-01",
      "currency": "USD",
      "status": "Sent",
      "description": "Brand identity package",
      "line_items": [
        { "description": "Logo design", "quantity": 1, "rate": 1200 },
        { "description": "Brand guidelines", "quantity": 1, "rate": 800 }
      ]
    }'
  ```

  ```js JavaScript theme={null}
  const res = await fetch('https://kliio.app/api/v1/invoices', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      client_id: 'c1d2e3f4-...',
      amount: 2000,
      due_date: '2025-05-01',
      currency: 'USD',
      status: 'Sent',
      line_items: [
        { description: 'Logo design', quantity: 1, rate: 1200 },
        { description: 'Brand guidelines', quantity: 1, rate: 800 }
      ]
    })
  })
  const { data } = await res.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "success": true,
    "data": {
      "id": "inv-uuid-...",
      "invoice_number": "INV-0043",
      "amount": 2000,
      "currency": "USD",
      "status": "Sent",
      "due_date": "2025-05-01",
      "tax_rate": 0,
      "description": "Brand identity package",
      "line_items": [
        { "description": "Logo design", "qty": "1", "rate": "1200", "discount": "0" },
        { "description": "Brand guidelines", "qty": "1", "rate": "800", "discount": "0" }
      ],
      "client": {
        "id": "c1d2e3f4-...",
        "name": "Alice Johnson",
        "email": "alice@example.com",
        "company_name": "Acme Corp"
      },
      "created_at": "2025-03-20T09:00:00.000Z"
    }
  }
  ```

  ```json 400 theme={null}
  {
    "error": "Validation failed",
    "details": {
      "due_date": ["due_date is required"]
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": "Client not found or access denied"
  }
  ```
</ResponseExample>