Edit a bill (accounts payable)

Edits an existing bill, i.e. an accounts payable record, and returns the updated bill. Every field is optional; an omitted field is left unchanged. Editable fields: vendor (an existing Books counterparty id — unlike create, a recipient alias is not accepted on edit), referenceNumber, effectiveDate and dueDate (both YYYY-MM-DD), notes, and lineChanges. lineChanges has three optional lists: create (new lines, each with a ledgerId, description, and dollar amount), update (existing lines by id, each field optional), and delete (existing line ids). As with create, a line amount may be negative, zero-amount lines are ignored, and the lines must total more than zero. The response is the updated bill, in the same shape the create and retrieve endpoints return. Limits: a cancelled bill cannot be edited. A paid bill accepts only changes to existing lines' ledgerId. A bill matched to a transaction that is not yet fully paid (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 bill with accrual schedules cannot be edited. A bill created from Bill Pay may only have its line categories (ledgerId) changed; any other change is rejected. 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 vendor counterparty does not belong to this organization. The id must be a bill: editing an invoice through this endpoint returns 404, 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 bill to edit, as returned by createBooksBill.

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 bill (accounts payable). Every field is optional;
an omitted field is left unchanged.

date | null

A new due date for the bill.

date | null

A new effective date for the bill (e.g. the bill date).

lineChanges
object | null

Changes to the bill's line items.

string | null

New notes or memo for the bill.

string | null

A new reference number (e.g. the vendor's bill number). Non-empty; leading
and trailing whitespace is stripped. Clearing the reference number is not
supported.

uuid | null

A new vendor for the bill, as a canonical Books counterparty ID. Unlike
create, a recipient alias is not accepted on edit.

Headers
string
Responses

400

Invalid body or Idempotency-Key or booksId

404

billId 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