Create an invoice

​

Creates a one-off 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.

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.

Body
required
application/json

Invoice attributes, wrapped in an invoice key.

  • invoice
    Type: object
    required
Responses
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/public-api/v1/invoices
curl https://app.hellobonsai.com/public-api/v1/invoices \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "invoice": {
    "company_id": 42,
    "contact_id": 7,
    "project_id": 51,
    "currency": "USD",
    "title": "Acme Corp Invoice",
    "due": "upon_receipt",
    "due_date": "2026-04-28",
    "invoice_items": [
      {
        "name": "Design",
        "description": "Homepage and pricing page",
        "amount": "2",
        "rate": "100",
        "unit_type": "flat"
      }
    ]
  }
}'

{
  "data": {
    "id": 3310,
    "invoice_number": "INV-001",
    "title": "Acme Corp Invoice",
    "currency": "USD",
    "issued_date": "2026-04-14",
    "due_date": "2026-04-28",
    "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",
    "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"
  }
}

The invoice was created as a draft.