Delete or cancel an invoice

​

Deletes a draft, or cancels an invoice that has been sent or is scheduled to send. Either way it stops appearing in GET /invoices, and you get it back one last time with status: deleted. Which of the two happens depends on the invoice's status when you call:

  • drafted invoices are deleted.
  • scheduled, outstanding and overdue invoices are cancelled. The app keeps the invoice number and its history. A scheduled invoice is never sent, and for a sent one the payment link your client has stops accepting payment.

Hours and expenses billed on the invoice go back to unbilled so they can be invoiced again. Nothing you logged is deleted.

Deleting an older invoice of a recurring series or subscription leaves the series running. The most recent one carries the schedule, so it is refused while the series is live: stop the recurrence first with DELETE /invoices/{invoice_id}/recurrence, then delete it.

The call returns 422 and changes nothing when the invoice is paid, has a payment or refund in progress, has payments recorded against it, is the deposit a contract or proposal is waiting on, is the most recent invoice of a live series, or is part of an invoice bundle. The error says which, and what to do instead. Most of these have to be handled in the Bonsai app.

An invoice that has already been deleted returns 404, like any id this token cannot see. There is no undo through the API.

Path Parameters

  • id
    Type: integer
    required

    Id of the invoice to delete or cancel.

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for delete/public-api/v1/invoices/{id}
curl https://app.hellobonsai.com/public-api/v1/invoices/1 \
  --request DELETE \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

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

The invoice was deleted or cancelled. data is the invoice as it was removed, with status: deleted.