Retrieve the current Invoice using the QBO REST API to obtain the latest SyncToken value; this token changes on every write and is required to prevent conflicting updates.
Construct a JSON request body containing at minimum: the Invoice Id, the current SyncToken, the field(s) you want to update, and the property "sparse": true at the top level of the body object.
Send a POST request to the QBO v3 Invoice endpoint (e.g., /v3/company/{realmId}/invoice) with the Content-Type set to application/json and the sparse body.
Check the response for a successful updated Invoice object; the response will include a new SyncToken which must be used for any subsequent updates.
If the server returns a stale SyncToken error (business validation fault), re-fetch the Invoice to get the latest SyncToken and retry the update.
For production usage, implement optimistic concurrency handling so concurrent writers re-read and re-attempt rather than silently overwriting each other's changes.
Known gotchas
The "sparse": true flag must be placed inside the JSON request body alongside Id and SyncToken — it is NOT a URL query parameter; placing it in the query string will be ignored and the update may behave as a full replace.
Omitting SyncToken or sending an outdated SyncToken will result in a concurrency conflict error; always read the current SyncToken immediately before writing to minimize the stale-token window.
In a sparse update, only the fields present in the body are modified; fields omitted are preserved — but line items behave differently and may require the full lines array to avoid unintended removal.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp