---
title: "Create a new invoice"
method: POST
path: "/invoices"
tags: ["Invoices"]
---

# Create a new invoice

`POST /invoices`

Creates a new invoice with line items. Returns the invoice with calculated totals.

## Request body

- object
  - `clientId` string, required — Client public ID (required)
  - `date` string, date-time, required — Invoice date
  - `dueDate` string, date-time, required — Due date
  - `lineItems` object[], required — Invoice line items
    - `name` string, required — Line item name
    - `productId` string, nullable — Product public ID (optional)
    - `quantity` number — Quantity
    - `price` number — Unit price
    - `description` string, nullable — Line item description
    - `taxRateId` string, nullable — Tax rate public ID
    - `discount` number — Discount value
    - `discountType` 'fixed' | 'percent' — Discount type: fixed amount or percent
    - `buyPrice` number — Cost/buy price
  - `isInclusiveTax` boolean — Whether prices include tax
  - `status` 'DRAFT' | 'SENT' — Invoice status (DRAFT or SENT)
  - `contactId` string, nullable — Contact public ID
  - `subject` string, nullable — Invoice subject
  - `notes` string, nullable — Invoice notes
  - `salesPersonId` string, nullable — Sales person user public ID
  - `templateId` string, nullable — Document template public ID. If not provided, uses the team's default invoice template.
  - `tags` number[] — Tag IDs to associate with the invoice

## Response `200`

OK

- object
  - `id` string, required — Invoice public ID
  - `number` string, required — Auto-generated invoice number
  - `date` string, date-time, required — Invoice date
  - `dueDate` string, date-time, required — Invoice due date
  - `status` string, required — Invoice status
  - `clientId` string, nullable — Client public ID
  - `contactId` string, nullable — Contact public ID
  - `currency` string, required — Currency code
  - `isInclusiveTax` boolean, required — Whether prices include tax
  - `subject` string, nullable — Invoice subject
  - `notes` string, nullable — Invoice notes
  - `salesPersonId` number, nullable — Sales person user ID
  - `subTotal` number, required — Subtotal before tax
  - `taxTotal` number, required — Total tax amount
  - `discountTotal` number, required — Total discount amount
  - `total` number, required — Grand total
  - `pendingTotal` number, required — Amount pending
  - `paidTotal` number, required — Total amount paid
  - `lineItems` object[], required — Invoice line items
    - `name` string, required — Line item name
    - `description` string, nullable — Line item description
    - `productId` number, nullable — Product ID
    - `quantity` number, required — Quantity
    - `price` number, required — Unit price
    - `tax` number, required — Tax percentage
    - `discount` number, required — Discount value
    - `discountType` 'fixed' | 'percent', required — Discount type
    - `buyPrice` number, required — Cost/buy price
    - `viewType` 'LINE_ITEM' | 'HEADING', required — Line item type
    - `amount` number, required — Line total after discount and tax
    - `taxAmount` number, required — Tax amount for this line
    - `discountAmount` number, required — Discount amount for this line
  - `createdAt` string, date-time, required — When the invoice was created
  - `customFields` object, nullable — Custom field values

---

[API](https://skmtc.net/heffl/apis/heffl-api-v2-beta.md) · [All operations](https://skmtc.net/heffl/apis/heffl-api-v2-beta/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/heffl/heffl-api-v2-beta/revisions/27006cfef4d8/schema)