HEhellobonsai
Invoices

Create an invoice

Creates an invoice, with its line items inline if you have them. company_id, contact_id and project_id are all required — an invoice is always for one client, addressed to one person, against one project.

kind decides whether this is a one-off, a recurring invoice or a subscription. A recurring invoice starts reissuing itself shortly after it is created, so send repeat_finish_date if the series has an end.

The project has to exist already and belong to the same client as company_id. This endpoint never creates one; use POST /public-api/v1/projects first if you need to.

The invoice is created as a draft. Nothing is sent to your client here — send it from Bonsai when you are ready.

Referencing a company, contact or project that is not in your account fails with 422 not_accessible rather than 404: the invoice is what you addressed, and the ids inside it are attributes of that request.

post/public-api/v1/invoices

Request

  • Base URL
    https://app.hellobonsai.com
  • URL
    https://app.hellobonsai.com/public-api/v1/invoices
  • Auth
    • OAuth 2
      Authorization code: https://app.hellobonsai.com/oauth/authorize
      Token URL: https://app.hellobonsai.com/oauth/token
    • or HTTP bearer

Request body

Example request

{
  "invoice": {
    "company_id": 42,
    "contact_id": 7,
    "project_id": 51,
    "currency": "USD",
    "title": "Acme Corp Invoice",
    "due_date": "2026-04-28",
    "repeat_finish_date": "2027-04-28",
    "invoice_items": [
      {
        "name": "Design",
        "description": "Homepage and pricing page",
        "amount": "2",
        "rate": "100"
      }
    ]
  }
}

Response

The invoice was created as a draft.

Example response

{
  "data": {
    "id": 3310,
    "invoice_number": "INV-001",
    "title": "Acme Corp Invoice",
    "currency": "USD",
    "issued_date": "2026-04-14",
    "due_date": "2026-04-28",
    "sent_date": "2026-04-14T09:12:04.000Z",
    "project_id": 51,
    "client_email": "alex@example.com",
    "public_url_token": "x7f2a9c4b1e8d",
    "created_at": "2026-04-14T09:12:04.000Z",
    "total_amount": "200.0",
    "discount_amount": "25.0",
    "status": "outstanding",
    "due_date_option": "custom",
    "company_id": 42,
    "client_name": "Acme Corp",
    "subtotal": "200.0",
    "tax_amount": "0.0",
    "kind": "recurring",
    "repeat_interval": "monthly",
    "repeat_finish_date": "2027-04-14",
    "series_id": 3310,
    "recurrence_active": true,
    "url": "https://app.hellobonsai.com/invoices/3391",
    "invoice_items": [
      {
        "id": 4471,
        "name": "Design",
        "description": "Homepage and pricing page",
        "amount": "2.0",
        "rate": "100.0",
        "unit_type": "per_hour",
        "total": "200.0"
      }
    ]
  },
  "meta": {
    "request_id": "b1f0d2c4-7a9e-4c3b-8d5f-1e2a3b4c5d6e"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.