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

# Create an invoice

`POST /invoices`

Create an invoice for the authenticated team. The behavior depends on deliveryType: 'create' generates and finalizes the invoice immediately, 'create_and_send' also sends it to the customer, 'scheduled' schedules the invoice for automatic processing at the specified date.

## Request body

- object — Schema for creating an invoice. The deliveryType determines if it stays as a draft, gets finalized immediately, or gets scheduled for later processing.
  - `template` object, required — Invoice template details
    - `customerLabel` string
    - `title` string
    - `fromLabel` string
    - `invoiceNoLabel` string
    - `issueDateLabel` string
    - `dueDateLabel` string
    - `descriptionLabel` string
    - `priceLabel` string
    - `quantityLabel` string
    - `totalLabel` string
    - `totalSummaryLabel` string
    - `vatLabel` string
    - `subtotalLabel` string
    - `taxLabel` string
    - `discountLabel` string
    - `timezone` string
    - `paymentLabel` string
    - `noteLabel` string
    - `logoUrl` string, nullable
    - `currency` string
    - `dateFormat` string
    - `includeVat` boolean
    - `includeTax` boolean
    - `includeDiscount` boolean
    - `includeDecimals` boolean
    - `includePdf` boolean
    - `sendCopy` boolean
    - `includeUnits` boolean
    - `includeQr` boolean
    - `includeLineItemTax` boolean
    - `lineItemTaxLabel` string
    - `taxRate` number, nullable
    - `vatRate` number, nullable
    - `size` 'a4' | 'letter'
    - `deliveryType` 'create' | 'create_and_send' | 'scheduled'
    - `locale` string
    - `paymentEnabled` boolean
    - `paymentTermsDays` number
    - `emailSubject` string, nullable
    - `emailHeading` string, nullable
    - `emailBody` string, nullable
    - `emailButtonText` string, nullable
    - `paymentDetails` object — Payment details in TipTap JSONContent format
    - `fromDetails` object — Sender details in TipTap JSONContent format
    - `noteDetails` object — Default footer notes in TipTap JSONContent format for new invoices
  - `fromDetails` object — Sender details in TipTap JSONContent format
  - `customerId` string, uuid, required — Unique identifier for the customer (required)
  - `paymentDetails` object — Payment details in TipTap JSONContent format
  - `noteDetails` object — Additional notes for the invoice in TipTap JSONContent format
  - `dueDate` string, date-time — Due date of the invoice in ISO 8601 format. Defaults to issue date + payment terms (30 days) if not provided.
  - `issueDate` string, date-time — Issue date of the invoice in ISO 8601 format. Defaults to current date if not provided.
  - `invoiceNumber` string — Invoice number as shown to the customer (auto-generated if not provided)
  - `logoUrl` string, nullable — URL of the logo to display on the invoice
  - `vat` number, nullable — VAT amount for the invoice
  - `tax` number, nullable — Tax amount for the invoice
  - `discount` number, nullable — Discount applied to the invoice
  - `topBlock` object — Custom content block to display at the top of the invoice in TipTap JSONContent format
  - `bottomBlock` object — Custom content block to display at the bottom of the invoice in TipTap JSONContent format
  - `amount` number, nullable — Total amount of the invoice
  - `lineItems` object[] — List of line items for the invoice
    - `quantity` number
    - `unit` string, nullable
    - `price` number
    - `vat` number, nullable
    - `tax` number, nullable
    - `taxRate` number, nullable
    - `name` object — Line item description in TipTap JSONContent format
    - `productId` string, uuid — Optional reference to a saved product
  - `deliveryType` 'create' | 'create_and_send' | 'scheduled', required — How the invoice should be processed: 'create' - finalize immediately, 'create_and_send' - finalize and send to customer, 'scheduled' - schedule for automatic processing at specified date
  - `scheduledAt` string, date-time — Scheduled date of the invoice in ISO 8601 format with timezone offset (e.g., Z or +00:00). Required when deliveryType is 'scheduled'. Must be in the future.

## Response `201`

Invoice created successfully. Status depends on deliveryType: 'scheduled' for scheduled invoices, 'unpaid' for create/create_and_send.

- object — Response after creating a draft invoice
  - `id` string, uuid, required — Unique identifier for the draft invoice
  - `status` 'draft' | 'overdue' | 'paid' | 'unpaid' | 'canceled' | 'scheduled', required — Current status of the invoice
  - `createdAt` string, required — Timestamp when the invoice was created (ISO 8601)
  - `updatedAt` string, required — Timestamp when the invoice was last updated (ISO 8601)
  - `pdfUrl` string, nullable, required — Direct URL to download the invoice PDF
  - `previewUrl` string, nullable, required — Direct URL to preview the invoice in browser

## Other responses

- `400` — Bad request. Invalid input data or validation errors.
- `404` — Customer not found.
- `409` — Conflict. Invoice number already exists.
- `500` — Internal server error.

---

[API](https://skmtc.net/midday-ai/apis/midday-api.md) · [All operations](https://skmtc.net/midday-ai/apis/midday-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/midday-ai/midday-api/versions/c0df9243c1b0/schema)