File debit-note draft
create_debit_note_draftFile a SELL-SIDE DEBIT NOTE draft into Taokeh — an ADDITIONAL CHARGE on an invoice this business already issued (an undercharge, a price revised upward after delivery, a surcharge that was missed). This does NOT post to the books: it creates a pending draft the user reviews and approves in Taokeh, and only then does it increase what the customer owes and the output SST. Shape the fields with intake_contract(doc_type:'sales_debit_note') first. THE ORIGINAL INVOICE IS REQUIRED: find it with search_documents and pass its id as originalDocId. There is no allowance or standalone shape here — unlike a credit note, a debit note with no invoice behind it is not a document; if there is nothing to correct upward, the right document is a NEW INVOICE (create_invoice_draft), so say that rather than filing this. CHARGE THE SHORTFALL, NOT THE NEW PRICE: unitAmount is the amount being ADDED per unit, and quantity defaults to 1 because an additional charge is usually one line of money. Every line must name a product that actually appears on that invoice; anything else is refused. MONEY ONLY, ALWAYS — a debit note moves no stock, touches no COGS, and has no restock option anywhere in Taokeh (there is no goodsReturned field on this tool and no checkbox on its review screen), so a one-tap approval is money-only by construction and not by fence — and posts only the figure the user saw: if the draft now works out to a different total (for example an SST change since you filed it), the one tap is refused and the user posts it from the full review page. If EXTRA GOODS were delivered, raise a new invoice instead. There is NO cap on the charge, so the approver is shown the original invoice's own total beside yours — keep the figure defensible. An invoice already REVERSED from a Shopee, TikTok or Shopify Returns page is refused when you file and again at approval (its reversing journal entry has cancelled the order in the books, so a debit note would charge an order that no longer exists). Set needsReview and add a SHORT reviewer note in notes (one or two sentences naming what to double-check) for any doubt. Filed it wrong? Use revise_draft (kind: 'sales_debit_note') rather than filing a second one. This is the SELL side; Taokeh's /debit-notes page is the separate BUY side (a purchase return against a supplier bill), which has no AI lane for CREATING one — a buy-side note already posted can only be corrected, with update_supplier_debit_note_draft. A sell-side debit note already posted has no correction lane at all: the owner voids it in Taokeh and a new one is filed. ⛔ LINE KEYS ARE STRICT (2026-09-09): a key this schema does not list is REFUSED BY NAME — with the key it probably meant — and NOTHING is filed. Unknown keys used to be dropped in silence, which let a line through with its price or its tax code missing.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lines | Yes | ||
| notes | No | A SHORT reviewer note: one or two plain sentences, in the reviewer's language, naming what the human should double-check before approving — which invoice you matched it to, where the figure came from. Not lengthy reasoning. | |
| dnDate | Yes | ||
| reason | No | Why more is charged — 'price revised upward after delivery', 'surcharge missed'. It prints on the note. | |
| customer | No | OPTIONAL CROSS-CHECK: the customer you believe the invoice belongs to. The customer comes FROM the invoice; sending a name that does not match is refused, which is exactly what it is for. | |
| reference | No | The debit-note number already printed on paper, if any. Leave it out and Taokeh numbers it (DN…). | |
| customerId | No | The resolved customer id, as the same cross-check. | |
| needsReview | No | ||
| printedTotal | No | The total printed on the paper, if any. Cross-check only — the server computes the real total and flags a mismatch on the approval screen. | |
| originalDocId | No | REQUIRED (this or originalDocNumber): the ORIGINAL invoice's id, from search_documents. The server verifies it exists, is an INVOICE and whose it is — it never guesses, and it will not file a debit note without one. | |
| originalDocNumber | No | The printed invoice number, when you have no id. Refused if more than one document carries it — find the right one with search_documents. |