Invoice

A bill you send to a client for work on one project, with its line items.

client_email
Type: string | null
required

Email address the invoice is addressed to, captured from the client contact when the invoice was created.
client_name
Type: string | null
required

Name the invoice is addressed to.
company_id
Type: integer | null
required

Id of the company being invoiced, or null when the invoice is addressed to a client that is not a company record.
created_at
Type: string Format: date-time
required

When the invoice was created.
currency
Type: string
required

Three-letter ISO 4217 currency code every amount on the invoice is expressed in.
discount_amount
Type: string | null
required

Discount taken off the subtotal, as a decimal string, or null when there is none.
due_date
Type: string | null Format: date
required

Date payment is due, or null when the invoice is payable on receipt.
due_date_option
Type: string | null enum
required

How due_date was arrived at: upon_receipt, after_x_days (a fixed number of days after the issue date) or custom (an explicit date).
values
- upon_receipt
- after_x_days
- custom
- null
id
Type: integer
required

Unique identifier for the invoice.
invoice_items
Type: array object[] · InvoiceItem[]
required

The invoice's line items, in the order they appear on it.
A single line on an invoice: what you are billing for, how much of it, and at what rate.
- amount
  Type: string | null
  required
  
  Quantity billed, as a decimal string.
- description
  Type: string | null
  required
  
  Longer description shown beneath the name, or null.
- id
  Type: integer
  required
  
  Unique identifier for the line item.
- name
  Type: string | null
  required
  
  Line item name, as it appears on the invoice.
- rate
  Type: string | null
  required
  
  Price per unit, as a decimal string in the invoice currency.
- total
  Type: string
  required
  
  amount multiplied by rate, rounded, as a decimal string.
- unit_type
  Type: string | null enum
  required
  
  What the rate is charged per. Defaults to flat.
  
  values
  flat
  per_hour
  per_day
  per_item
  per_word
invoice_number
Type: string | null
required

Human-readable invoice reference, unique within your account. The list endpoint accepts it as filter[invoice_number].
issued_date
Type: string | null Format: date
required

Date the invoice was sent to the client, or null while it is still a draft.
project_id
Type: integer | null
required

Id of the project the invoice bills.
public_url_token
Type: string | null
required

Token in the invoice's client-facing URL. Anyone holding that link can view and pay the invoice, so treat this value as a secret.
status
Type: string enum
required
Where the invoice is in its lifecycle:
- new, drafted — not sent to the client yet.
- scheduled — queued to send automatically on a future date.
- outstanding — sent and awaiting payment.
- overdue — sent, unpaid and past due_date.
- pending — a payment has started but has not settled.
- paid — paid in full.
- deleted — the invoice has been deleted.
An invoice that is paid or pending can no longer be edited, and neither can its line items.
values
- new
- drafted
- scheduled
- outstanding
- overdue
- pending
- paid
- deleted
subtotal
Type: string | null
required

Sum of every line item, before discount and tax, as a decimal string.
tax_amount
Type: string | null
required

Tax added to the invoice, as a decimal string.
title
Type: string | null
required

Invoice title shown to the client.
total_amount
Type: string
required

What the client owes, as a decimal string, after any discount and tax.
url
Type: string
required

Absolute link to the invoice in the Bonsai app. This is the contractor-facing view, not the client payment page — for that, use public_url_token.