Invoices

An invoice is generated for a client from its unbilled time entries, services, expenses, or fixed price projects, then optionally emailed to the client’s recipients. For fields and response details, see the API reference.

List invoices

List the workspace’s invoices, newest issue date first. Filter by client, status, issue date range, or --overdue to see only unpaid invoices whose due date has passed. Deleted invoices are left out. The command accepts --page and --page-size, and reports a pagination object in the envelope. See Pagination.

neetoinvoice invoices list --overdue

Flag	Type	Required	Default	Description
`--client`	`string`	No		Only this client’s invoices (identifier or ID)
`--end-date`	`string`	No		Issued on or before this date (YYYY-MM-DD)
`--overdue`	`bool`	No	`false`	Only unpaid invoices past their due date
`--page`	`int`	No	unset	Page number
`--page-size`	`int`	No	unset	Items per page (max 100)
`--start-date`	`string`	No		Issued on or after this date (YYYY-MM-DD)
`--status`	`string`	No		Filter by status: generating, generated, paid, written_off, failed or pending_payment

Each invoice shows total before tax, grand_total after discount and tax, amount_paid, amount_due, and days_overdue, which is 0 when the invoice is not overdue. For fields and response details, see the API reference.

Sample output (--json)

{
  "data": [
    {
      "id": "6be815a8-9a10-455c-95d9-b0b548664420",
      "identifier": "a1b2c3",
      "number": "INV-2026-030",
      "status": "generated",
      "client_id": "3f0c0f87-ddc7-45f4-ad7a-c3690fa04963",
      "client_name": "Acme",
      "currency": "USD",
      "issue_date": "2026-08-20",
      "due_date": "2026-09-04",
      "sent_date": "2026-08-20",
      "total": 2400.0,
      "grand_total": 2400.0,
      "amount_paid": 0.0,
      "amount_due": 2400.0,
      "days_overdue": 41
    }
  ],
  "breadcrumbs": [
    {
      "label": "Send",
      "command": "neetoinvoice invoices send <invoice> --client <client-id>"
    }
  ],
  "pagination": {
    "total_records": 1,
    "total_pages": 1,
    "current_page_number": 1,
    "page_size": 30
  }
}

Create an invoice

Generate an invoice. Scalar fields are available as flags; line items, taxes, and email details are passed as a JSON file with --json-file. Flag values override the file’s top-level keys, so you can keep a template file and vary the number and dates per run. To bill unbilled time entries by ID, repeat --time-entry-id. --user-email is needed only when you sign in with an API key.

neetoinvoice invoices create \
  --client 7c1f5e2a9b \
  --user-email oliver@example.com \
  --number INV-EXT-001 \
  --issue-date 2026-07-14 \
  --due-date 2026-08-13 \
  --project-id 89d1b47d9f36af3c9ecf \
  --json-file ./invoice.json

Flag	Type	Required	Default	Description
`--client`	`string`	Yes		Client identifier
`--due-date`	`string`	No		Due date (YYYY-MM-DD)
`--issue-date`	`string`	No		Issue date (YYYY-MM-DD)
`--json-file`	`string`	No		Path to a JSON file with the full invoice payload (line items, taxes, email details)
`--notes`	`string`	No		Invoice notes
`--number`	`string`	Yes		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
`--time-entry-id`	`stringSlice`	No	`[]`	Unbilled time entry ID to bill (repeatable)
`--user-email`	`string`	No		Email of the acting organization user (needed only with an API key)

Dates use YYYY-MM-DD, like every other command.

The `--json-file` file

The file holds the full invoice payload. An invoice needs at least one of invoice_time_entries, invoice_services, invoice_expenses, or a fixed price project passed with --project-id. Billing unbilled time entries:

invoice.json

{
  "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:

invoice.json

{
  "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. Billing an expense. Each expense needs notes, unit_amount and recorded_on. category is the name of an expense category set up in the workspace, and the match is case-insensitive:

invoice.json

{
  "invoice_expenses": [
    {
      "notes": "Flight to client site",
      "unit_amount": 320.0,
      "quantity": 1,
      "recorded_on": "2026-07-12",
      "category": "Travel"
    }
  ]
}

Emailing the invoice

Pass --send-email and the invoice is emailed once it is generated. Without invoice_details.recipient_ids, every current recipient of the client receives it. To narrow it, put the email details in the data file. recipient_ids are the client’s recipients; find them with clients show.

invoice.json

{
  "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"]
  }
}

neetoinvoice invoices create \
  --client 7c1f5e2a9b \
  --user-email oliver@example.com \
  --number INV-EXT-001 \
  --send-email \
  --json-file ./invoice.json

Taxes

Add a tax_details array to the data file:

invoice.json

{
  "tax_details": [
    { "name": "GST", "percentage": 10, "notes": "Goods and Services Tax", "selected": true }
  ]
}

Output

Sample output (--json)

{
  "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>" }
  ]
}

Send an invoice

Email a generated invoice to the client’s recipients and mark it as sent. Every current recipient of the client receives it unless you repeat --recipient-id to name some of them. Only a generated invoice can be sent. Sending the same invoice again delivers it again.

neetoinvoice invoices send INV-2026-042 \
  --client 7c1f5e2a9b \
  --attach-pdf

Required arguments:

<invoice> - The invoice number as printed on the document, its identifier, or its ID.

Flag	Type	Required	Default	Description
`--attach-pdf`	`bool`	No	`false`	Attach the invoice PDF
`--client`	`string`	Yes		Client identifier or ID
`--message`	`string`	No		Email message
`--recipient-id`	`stringSlice`	No	`[]`	Recipient ID to email (repeatable; default: every current recipient)
`--send-me-a-copy`	`bool`	No	`false`	Also email a copy to the acting user
`--subject`	`string`	No		Email subject
`--user-email`	`string`	No		Email of the acting organization user (needed only with an API key)

For fields and response details, see the API reference.

Sample output (--json)

{
  "data": {
    "message": "Invoice 'INV-2026-042' emailed to billing@acme.example.com and ap@acme.example.com.",
    "id": "6be815a8-9a10-455c-95d9-b0b548664420",
    "number": "INV-2026-042",
    "sent_date": "2026-10-15",
    "recipient_emails": ["billing@acme.example.com", "ap@acme.example.com"]
  }
}

Getting started

Commands

List invoices

Create an invoice

The `--json-file` file

Emailing the invoice

Taxes

Output

Send an invoice

​List invoices

​Create an invoice

​The --json-file file

​Emailing the invoice

​Taxes

​Output

​Send an invoice

List invoices

Create an invoice

The `--json-file` file

Emailing the invoice

Taxes

Output

Send an invoice