---
title: "Edits a draft invoice's header (number, dates, terms, notes, payment instructions, tax rate)."
method: PATCH
path: "/api/v1/invoices/{id}"
tags: ["Invoices"]
---

# Edits a draft invoice's header (number, dates, terms, notes, payment instructions, tax rate).

`PATCH /api/v1/invoices/{id}`

## Request

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

Requires `ManageInvoices` and an `Idempotency-Key` header. PATCH semantics: only the
fields you send change. Only a `Draft` invoice can be edited (a finalized invoice is
immutable — void it and issue a new one). Totals are not editable here: the subtotal comes
from the job, so recompute it with `POST /api/v1/invoices/{id}/refresh-from-job` after the
job's lines change. The write is attributed to the user who created the key.

## Path parameters

- `id` integer, required

## Request body

- UpdateInvoiceDraftApiRequest: Body of `PATCH /api/v1/invoices/{id}`: a partial edit of a <b>draft</b> invoice's header. Only the fields you send change; omitted fields are left as they are. Totals are not editable here — the subtotal comes from the job, so recompute it with `POST /api/v1/invoices/{id}/refresh-from-job` after the job's lines change.
  - `invoiceNumber` string, nullable: New invoice number shown to the customer (e.g. `INV-1042`). Omit to leave unchanged; blank is rejected.
  - `invoiceDate` string, date-time, nullable: New issue date (ISO-8601; the date part is used). Omit to leave unchanged.
  - `dueDate` string, date-time, nullable: New due date (ISO-8601; the date part is used). Omit to leave unchanged.
  - `taxRate` number, double, nullable: New tax rate as a percentage, 0–100 (e.g. `8.25`). Omit to leave unchanged.
  - `terms` string, nullable: New payment terms printed on the invoice (e.g. `Due on Receipt`). Omit to leave unchanged; empty string clears it.
  - `notes` string, nullable: New customer-facing notes printed on the invoice. Omit to leave unchanged; empty string clears it.
  - `paymentInstructions` string, nullable: New payment instructions printed on the invoice. Omit to leave unchanged; empty string clears it.

## Response `200`

The updated invoice.

- 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, missing `Idempotency-Key`, or a tax rate out of 0–100.
- `401`: Unauthorized
- `403`: Forbidden
- `404`: No such invoice in the calling organization.
- `409`: The invoice is not a draft, or the key's creator is unknown on this server.
- `422`: The invoice number was sent blank.
- `429`: Too Many Requests

---

[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)