File a pending correction draft for a posted bill (admin approves in Taokeh)
update_bill_draftFILES A PENDING DRAFT ONLY — NOTHING CHANGES UNTIL A HUMAN REVIEWS AND APPROVES IT IN TAOKEH. Propose a correction to a supplier bill ALREADY POSTED in Taokeh — the door for a bill that went onto the books with a wrong line, a wrong quantity or cost, the wrong date, the wrong payment term or the wrong payment method. To change, add or remove LINES, read them first with search_document_lines (docType 'bill') and NAME each line you keep with its lineNo (or send { keep: } for a line that is already right): a line with a lineNo IS that line of the bill, a line without one is a NEW line, and a line you leave out is REMOVED — on a bill that received goods against a purchase order, a removed line's goods go back to being owed on the order (see lines). It files a pending DRAFT an ADMIN reviews as a DIFF (current → proposed) and approves; only that tap rewrites the bill, and it keeps the SAME bill number, the original attached document, and the link to the purchase order the bill was converted from. Pass purchaseId, the bill's REAL id from search_documents — a bill number is refused, because two suppliers can print the same number and correcting the wrong one is worse than asking. ROUTING — three different mistakes, three different doors. (1) THE PURCHASE NEVER HAPPENED (keyed twice, entered on the wrong company, the wrong supplier's bill): the owner VOIDS it — Purchasing → the bill → Void, in Taokeh. There is deliberately NO AI lane for voiding. Tell them where to click. (2) THE PURCHASE HAPPENED BUT THE BILL IS WRONG (a wrong line, quantity or unit cost, the wrong date, term, due date or payment method): THIS tool. (3) SOMETHING CHANGED AFTER THE PURCHASE (goods went back to the supplier, the supplier credited a price difference later): a DEBIT NOTE against the bill, which the owner raises in Taokeh (Purchasing → Debit notes) — a real event that belongs on the books as its own document. WHAT YOU CAN CHANGE: purchaseDate, paymentMethod ('CASH' paid on the spot, or 'CREDIT' on account), term (the supplier's payment term, stored as written — changing an on-account bill to one of the five presets, Due on Receipt / Net 7 / Net 14 / Net 30 / Net 60, re-derives the due date from the bill date unless you also send dueDate), dueDate (only when the due date ITSELF is wrong — correcting just the bill date already moves the due date by the same number of days), and lines — the FULL REPLACEMENT SET, so send every line the bill should have, including the ones that were already right. Everything you do NOT send is carried across exactly as the bill has it: the supplier, the currency and its frozen exchange rate, the location the goods were received into, the batch (lot) each line was received into, and each line's SST code. On a bill with no purchase order each replacement line keeps the UNIT it has on the bill: a line identical to one of the bill's own lines keeps that line's unit, any other line takes the product's one unit on the bill (a product new to the bill: its own unit). Here unit is only the price basis — it never sets a line's unit — and a line measured from its size and tally is booked in the measurement's unit (tons for timber). When the product is on the bill in more than one unit, a changed line of it that is not measured is refused, and the user makes that change on the bill's Edit screen in Taokeh. Batches: without line numbers, a replacement line of a product the bill already carries is received into the same batch as the original line of that product; with line numbers, a named line keeps its own batch and a NEW line of a product the bill already received into stock goes into that product's lot on the bill, by lot number (the lot keeps its own expiry) — refused when the bill received it into more than one lot (raise the quantity on the right line instead). WHAT YOU CANNOT, each refused by name: the SUPPLIER (a different supplier is a different document — the owner voids and re-enters); the BILL NUMBER (preserved across an edit; Taokeh's own Edit screen cannot change it either); the CURRENCY or the RATE (frozen at posting); and a bill posted with a whole-document tax rate instead of per-line SST codes (Taokeh does not store that rate, so a correction from here would drop the input tax — the owner corrects it on the app's Edit screen). WHAT BLOCKS AN EDIT OUTRIGHT, checked when you file and again when the admin taps, each refusal naming the real next step: the document is not a bill (an opening balance or a debit note has its own page); it is validated on MyInvois as a self-billed e-invoice; a live debit note has been raised against it; a payment has been allocated to it; or it is dated inside a period the company has locked. A proposal that changes nothing is refused rather than filed as an empty diff. If the bill is edited by someone else after you read it, the admin is shown BOTH versions and the one-tap approval is refused — that is by design; call revise_draft (kind 'bill_update') to re-read and re-propose. An edit in Taokeh re-books the bill under a NEW id with the same number: a pending draft FOLLOWS it, and calling this tool with the old id is refused with the new id named — re-read the bill before proposing against it.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| notes | No | A SHORT reviewer note in the reviewer's language: what was wrong, what you changed, and anything they should double-check before they approve a rewrite of a posted bill. | |
| proposed | Yes | ONLY what you want changed. An unknown or not-patchable key is refused by name; a proposal the bill already agrees with is refused rather than filed. | |
| purchaseId | Yes | REQUIRED — the posted bill's real id, from search_documents. A bill number is refused: correcting the wrong document silently is worse than asking which one they mean. | |
| needsReview | No | Set true when something gave you pause — it flags the draft for the reviewer. | |
| printedTotal | No | The grand total the corrected bill should show, if the user told you one — cross-checked against the server's own derivation and flagged on the review screen. |