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

# Create a new invoice

`POST /invoices`

## Request

- Base URL: `https://api.heffl.com/api/v1`
- URL: `https://api.heffl.com/api/v1/invoices`
- Auth: API key in header `x-api-key`

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.dev/heffl/apis/heffl-public-api-legacy-v1.md) · [All operations](https://skmtc.dev/heffl/apis/heffl-public-api-legacy-v1/llms.txt) · [OpenAPI document](https://skmtc.dev/heffl/apis/heffl-public-api-legacy-v1/revisions/9bdb229223a2?raw)