---
title: "Creates a standalone invoice (not tied to a job) from explicit lines."
method: POST
path: "/api/v1/invoices"
tags: ["Invoices"]
---

# Creates a standalone invoice (not tied to a job) from explicit lines.

`POST /api/v1/invoices`

## Request

- Base URL: `https://app.flexonthejob.com`
- URL: `https://app.flexonthejob.com/api/v1/invoices`
- Auth: HTTP bearer

Requires `ManageInvoices` and an `Idempotency-Key` header. The subtotal is
the sum of the lines; tax applies to all of it at `taxRate` (0 for a tax-exempt
customer). Every omitted field defaults exactly as the New Invoice page does (next
`INV-SA-…` number, today, the organization's default payment terms, tax rate and
payment instructions). Like that page, the invoice is created already finalized
(status `Sent`) — there is no draft step — so a payment can be recorded at once
with `POST /api/v1/invoices/{id}/payments`. To bill a job instead, use
`POST /api/v1/invoices/from-job`.

## Request body

- CreateStandaloneInvoiceApiRequest: Body of `POST /api/v1/invoices` — a standalone invoice (not tied to a job) with its own lines. Only `customerId` and at least one line are required; every omitted field defaults exactly as the New Invoice page does (number `INV-SA-…`, today, the organization's default payment terms, tax rate and payment instructions). The subtotal is always the sum of the lines; it is never accepted directly.
  - `customerId` integer: Numeric id of the customer to bill (must be an active customer in your organization).
  - `customerAddressId` integer, nullable: Optional site address id (a location belonging to the customer) to print on the invoice.
  - `invoiceNumber` string, nullable: Invoice number. Defaults to the next `INV-SA-…` number.
  - `invoiceDate` string, date-time, nullable: Issue date (UTC, date part only). Defaults to today.
  - `dueDate` string, date-time, nullable: Due date (UTC, date part only). Defaults from `paymentTerms`; must not precede `invoiceDate`.
  - `description` string, nullable: Short description shown in lists.
  - `taxRate` number, double, nullable: Tax rate percentage. Defaults to the organization's default rate; always 0 for a tax-exempt customer.
  - `paymentTerms` 'DueOnReceipt' | 'Net15' | 'Net30' | 'Net45' | 'Net60' | 'COD' | 'Prepaid'
  - `notes` string, nullable: Notes shown to the customer.
  - `paymentInstructions` string, nullable: Payment instructions printed on the invoice. Defaults to the organization's default instructions.
  - `lines` StandaloneInvoiceLineApiRequest[], required: Lines to bill, in display order. At least one.
    - `description` string, required: What is being billed.
    - `itemType` 'Material' | 'Labor' | 'Service' | 'Other'
    - `quantity` number, double: Quantity billed. Defaults to 1.
    - `unitOfMeasure` string, nullable: Unit of measure label (e.g. `ea`, `hr`), if any.
    - `unitPrice` number, double: Price per unit.
  - `applyStoreCredit` boolean: Apply `storeCreditToApply` of the customer's store credit to the new invoice.
  - `storeCreditToApply` number, double: Store credit amount to apply when `applyStoreCredit` is true (capped at the customer's balance and the invoice total). Ignored otherwise.

## Response `201`

The new invoice; `Location` points at it.

- InvoiceSummary: Invoice header as listed by `GET /api/v1/invoices`. Timestamps are ISO-8601 UTC (`2026-09-05T14:30:00Z`).
  - `id` integer: Numeric id, usable in `/api/v1/invoices/{id}`.
  - `syncId` string, uuid: Stable cross-device id; also the pagination cursor.
  - `invoiceNumber` string: Human-readable invoice number, e.g. `INV-1042`.
  - `status` 'Draft' | 'Sent' | 'Viewed' | 'PartiallyPaid' | 'Paid' | 'Overdue' | 'Cancelled' | 'Outstanding' | 'Consolidated'
  - `customerId` integer, nullable: Billed customer id, if any.
  - `customerName` string, nullable: Billed customer name, if any.
  - `jobId` integer, nullable: Job the invoice bills, if any.
  - `jobNumber` string, nullable: Job number, if any.
  - `salesOrderId` integer, nullable: Sales order the invoice bills, if any.
  - `description` string, nullable: Optional description.
  - `invoiceDate` string, date-time: Issue date, ISO-8601 UTC at midnight, e.g. `2026-09-05T00:00:00Z`.
  - `dueDate` string, date-time: Due date, ISO-8601 UTC at midnight, e.g. `2026-10-05T00:00:00Z`.
  - `subtotal` number, double: Sum of lines before tax.
  - `taxAmount` number, double: Tax charged.
  - `total` number, double: Subtotal plus tax.
  - `amountPaid` number, double: Payments applied.
  - `storeCreditApplied` number, double: Store credit applied.
  - `balanceDue` number, double: Total minus payments and store credit.
  - `isConsolidated` boolean: True when this invoice consolidates other invoices.
  - `consolidatedIntoInvoiceId` integer, nullable: Id of the consolidated invoice that absorbed this one, if any.
  - `sentDate` string, date-time, nullable: When the invoice was first sent, ISO-8601 UTC (e.g. `2026-09-05T14:30:00Z`); null if never sent.
  - `paidDate` string, date-time, nullable: When the invoice was paid in full, ISO-8601 UTC; null until paid.
  - `createdAt` string, date-time: Creation time, ISO-8601 UTC.
  - `updatedAt` string, date-time, nullable: Last modification time, ISO-8601 UTC; null when never edited. Use with the `updatedSince` filter to poll for changes.

## Other responses

- `400`: Malformed body, no lines, or an out-of-range value.
- `401`: Unauthorized
- `403`: Forbidden
- `409`: The invoice number is already used, or the key's creator is unknown on this server.
- `422`: Unknown `customerId` or `customerAddressId`, or `dueDate` precedes `invoiceDate`.
- `429`: Too Many Requests
- `500`: The invoice could not be saved.

---

[API](https://skmtc.dev/flexonthejob/apis/flex-api.md) · [All operations](https://skmtc.dev/flexonthejob/apis/flex-api/llms.txt) · [OpenAPI document](https://skmtc.dev/flexonthejob/apis/flex-api/revisions/19c8f4d27acf?raw)