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

# invoices

> Generate an invoice for a client from unbilled time entries or services.

An invoice is generated for a client from its unbilled time entries, services, or both, then
optionally emailed to the client's recipients. For fields and response details, see the
[API reference](/api-reference/invoices/create).

<Note>
  Sample responses on this page show the JSON envelope (`--json`). Pretty output is the
  default on a terminal and its columns adapt to width. See
  [Output formats](/cli/output-formats).
</Note>

## invoices create

Generate an invoice. Scalar fields are available as flags; line items, taxes, and email
details are passed as a JSON file with `--data`. Flag values override the file's top-level
keys, so you can keep a template file and vary the number and dates per run.

```bash theme={"system"}
neetoinvoice invoices create \
  --client 7c1f5e2a9b \
  --user-email oliver@example.com \
  --number INV-EXT-001 \
  --issue-date 07/14/2026 \
  --due-date 08/13/2026 \
  --project-id 89d1b47d9f36af3c9ecf \
  --data ./invoice.json
```

| Flag           | Type          | Required | Default | Description                                                                          |
| -------------- | ------------- | -------- | ------- | ------------------------------------------------------------------------------------ |
| `--client`     | `string`      | Yes      |         | Client identifier                                                                    |
| `--data`       | `string`      | No       |         | Path to a JSON file with the full invoice payload (line items, taxes, email details) |
| `--due-date`   | `string`      | No       |         | Due date (MM/DD/YYYY)                                                                |
| `--issue-date` | `string`      | No       |         | Issue date (MM/DD/YYYY)                                                              |
| `--notes`      | `string`      | No       |         | Invoice notes                                                                        |
| `--number`     | `string`      | No       |         | Invoice number                                                                       |
| `--project-id` | `stringSlice` | No       | `[]`    | Project ID(s) to invoice (repeatable)                                                |
| `--send-email` | `bool`        | No       | `false` | Email the invoice to the client's recipients                                         |
| `--user-email` | `string`      | Yes      |         | Email of the acting organization user                                                |

Dates use `MM/DD/YYYY`, unlike time entries, which use `YYYY-MM-DD`.

### The `--data` file

The file holds the full invoice payload. An invoice needs either `invoice_time_entries` or
`invoice_services`, plus a `total`.

Billing unbilled time entries:

```json invoice.json theme={"system"}
{
  "total": 500.0,
  "notes": "Payment terms: Net 30 days",
  "invoice_time_entries": [
    {
      "time_entry_id": "128c1dfc-b29f-4fda-9a05-8a90e197b81b",
      "project_id": "f627c399-379d-4d07-a6f6-90b7c9470ac0",
      "task_id": "24e6a2fe-31bb-686c-541a-9f36af3c9ecf",
      "user_id": "5a2de667-243b-4da3-b090-b698a03d98da",
      "notes": "Reviewed the new dashboard layout",
      "hours": 2.5,
      "hourly_rate": 120.0
    }
  ]
}
```

Billing a flat service instead:

```json invoice.json theme={"system"}
{
  "total": 500.0,
  "invoice_services": [
    {
      "notes": "Quarterly retainer",
      "quantity": 1,
      "unit_amount": 500.0,
      "project_id": "f627c399-379d-4d07-a6f6-90b7c9470ac0"
    }
  ]
}
```

Get `time_entry_id` values from
[`time-entries list`](/cli-reference/time-entries#time-entries-list).

### Emailing the invoice

Pass `--send-email` and put the email details in the data file. `recipient_ids` are the
client's recipients; find them with
[`clients show`](/cli-reference/clients#clients-show).

```json invoice.json theme={"system"}
{
  "total": 500.0,
  "invoice_services": [
    { "notes": "Quarterly retainer", "quantity": 1, "unit_amount": 500.0 }
  ],
  "invoice_details": {
    "subject": "Invoice INV-EXT-001 from Acme Corp",
    "message": "Please find attached your invoice for the services rendered.",
    "attach_pdf_invoice": "true",
    "send_me_a_copy": "false",
    "recipient_ids": ["128c1dfc-b29f-4fda-9a05-8a90e197b81b"]
  }
}
```

```bash theme={"system"}
neetoinvoice invoices create \
  --client 7c1f5e2a9b \
  --user-email oliver@example.com \
  --number INV-EXT-001 \
  --send-email \
  --data ./invoice.json
```

### Taxes

Add a `tax_details` array to the data file:

```json invoice.json theme={"system"}
{
  "tax_details": [
    { "name": "GST", "percentage": 10, "notes": "Goods and Services Tax", "selected": true }
  ]
}
```

### Output

```json theme={"system"}
{
  "data": {
    "notice_code": "thumbs_up",
    "invoice": {
      "id": "6be815a8-9a10-455c-95d9-b0b548664420",
      "number": "INV-EXT-001",
      "total": 500.0,
      "status": "sent",
      "issue_date": "2026-07-14",
      "due_date": "2026-08-13",
      "notes": "Payment terms: Net 30 days",
      "client_id": "3f0c0f87-ddc7-45f4-ad7a-c3690fa04963",
      "organization_id": "9f36af3c-9ecf-4d07-a6f6-90b7c9470ac0",
      "created_at": "2026-07-14T09:12:04.000Z",
      "updated_at": "2026-07-14T09:12:04.000Z"
    }
  },
  "breadcrumbs": [
    { "label": "Client", "command": "neetoinvoice clients show <client-id>" }
  ]
}
```