Edit an invoice (accounts receivable)

Edits an existing invoice, i.e. an accounts receivable (AR) record of money a customer owes the organization, and returns the updated invoice in the same shape the create (createBooksInvoice), retrieve (getBooksInvoice), and list (getBooksInvoices) endpoints return: its id, referenceNumber, customer, dates, status, displayStatus, amounts, lines, notes, and paymentApplications. Every field is optional; an omitted field is left unchanged. Editable fields: referenceNumber (the invoice number), customer (a Mercury Invoicing customer ID of this organization, from the Mercury Invoicing customers API, /ar/customers), effectiveDate (invoice date) and dueDate (both YYYY-MM-DD), notes, and lineChanges. lineChanges has three optional lists: create (new lines, each with a ledgerId, i.e. a general ledger (GL) account such as a revenue ledger, a description, and a dollar amount), update (existing lines by id, each other field optional), and delete (existing line ids). A line amount may be negative, and the lines must total more than zero. Limits: a cancelled invoice cannot be edited. A paid invoice, and an invoice synced with Mercury Invoicing that is paid or partially paid, accepts only changes to existing lines' ledgerId. Any other invoice matched to a transaction (partially paid) can still be edited, but its total and each line's amount cannot drop below what has already been paid on it, and a line with payments cannot be deleted (Teal enforces these). A paid or matched invoice with accrual schedules cannot be edited. If an edit to an invoice synced with Mercury Invoicing is saved there but has not synced to Books yet, the response is HTTP 202 with syncStatus: pending, the invoice id, and a message; read the invoice back with getBooksInvoice once it has synced instead of sending the edit again. On an invoice synced with Mercury Invoicing, customer may be sent only as the invoice's current customer, which is accepted; a different customer is rejected with an error on customer. Request errors are returned as an HTTP error status and change nothing: the token lacks the scope to update accrual sources, a line ledger is outside the Books instance or read-only, or the customer does not belong to this organization. The id must be an invoice: a bill ID returns 404 (use updateBooksBill to edit bills), as does an unknown id. To make retries safe, send an Idempotency-Key header: a lineChanges.create is not naturally idempotent, so without a key a retry after a timeout can append duplicate lines; a replay with the same key and body returns the original result instead (a reused key with a different body is rejected with 422).

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Path Params
string
required

The ID of the invoice to edit, as returned by getBooksInvoices or createBooksInvoice.

Query Params
uuid

The Books instance to act on. Required for agent organization tokens; defaults to the token organization's instance.

Body Params

A request to edit a single invoice (accounts receivable). Every field is
optional; an omitted field is left unchanged.

uuid | null

The customer to bill: a Mercury Invoicing customer ID of this organization, from the Mercury Invoicing customers API (/ar/customers). An invoice synced with Mercury Invoicing accepts only its current customer.

date | null

A new due date, YYYY-MM-DD.

date | null

A new invoice date, YYYY-MM-DD.

lineChanges
object | null

Changes to the invoice's line items.

string | null

A new note for the invoice.

string | null

A new invoice number, the number the customer sees (for example INV-1042). 1 to 299 characters; leading and trailing whitespace is stripped. Clearing it is not supported.

Headers
string
Responses

400

Invalid body or Idempotency-Key or booksId

404

invoiceId not found

Language
Credentials
Bearer
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json