File credit-note draft
create_credit_note_draftFile a CREDIT NOTE draft into Taokeh — a sales return, short delivery, price correction or allowance that reduces what a customer owes. This does NOT post to the books: it creates a pending draft the user reviews and approves in Taokeh, and only then does it reduce the customer's balance, reverse the revenue and SST, and (if the user says the goods came back) put stock back — and then only for the lines the ORIGINAL invoice actually shipped, and never more than it shipped: a line that moved no goods is money only, and claiming otherwise is refused at approval rather than posted. Shape the fields with intake_contract(doc_type:'credit_note') first. RESOLVE THE ORIGINAL INVOICE FIRST: a credit note is issued AGAINST an invoice — find it with search_documents and pass its id as originalDocId with kind:'against_invoice'. Only a credit with NO source invoice is kind:'allowance', and an allowance is never linked to an invoice, never capped by one, inherits no SST codes and never restocks — so do not file a real return as one; ask the user which invoice it is against. Send all amounts POSITIVE (Taokeh stores the credit note negative itself). A DISCOUNTED invoice line: send its own unit price (before discount) and Taokeh shares that line's discount out by quantity itself — you cannot send a discount, and the result lists each shared one under sharedDiscounts. A line can only credit back as MANY units as that invoice actually sold, net of earlier credit notes — an over-quantity line is refused naming what is left, so read the invoice's own unit of measure rather than converting it (1 carton is not 100 pieces). Whether goods physically came back into stock is the USER's decision at approval — goodsReturned is only a hint that pre-ticks their checkbox on the full review page, and a one-tap approval always posts money-only — and 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. 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: 'credit_note') rather than filing a second one. IS A CREDIT NOTE EVEN THE RIGHT DOCUMENT? Only when something CHANGED AFTER the sale — goods came back, a price was renegotiated, a discount was agreed later. If the sale simply never happened (keyed twice, wrong company, cancelled before delivery), the owner VOIDS the invoice instead: Sales → the invoice → Void, in Taokeh. There is deliberately no AI lane for voiding. And if the sale did happen but the invoice was typed wrong — wrong line, wrong quantity or price, wrong date — that is a correction, not a credit: use update_invoice_draft. An invoice already REVERSED from a Shopee, TikTok or Shopify Returns page is refused when you file (its reversing journal entry already credits it in full, so a credit note would credit it twice). And if a credit note ALREADY POSTED was itself typed wrong (a wrong line, quantity, price or date), do not file a second one on top — correct it with update_credit_note_draft. ⛔ 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 |
|---|---|---|---|
| kind | Yes | REQUIRED. 'against_invoice' = a return / short delivery / price correction on a SPECIFIC invoice (the usual case — give originalDocId or originalDocNumber). 'allowance' = a standalone money credit with NO source invoice (give the customer instead). They are different documents; when it isn't clear, ask the user which invoice it is against. | |
| 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 — whether the goods actually came back, an ambiguous quantity, which invoice you matched it to. Not lengthy reasoning. | |
| cnDate | Yes | ||
| reason | No | Why the credit is given — 'damaged goods returned', 'short delivery', 'agreed price adjustment'. It prints on the credit note. | |
| customer | No | allowance ONLY: the customer name, resolved with resolve_customer first. A credit note reduces an EXISTING customer's balance and can never create a customer. For an against_invoice credit note the customer comes from the invoice — leave this out. | |
| reference | No | The credit-note number already printed on paper, if any. Leave it out and Taokeh numbers it (CN…). | |
| customerId | No | allowance: the resolved customer id instead of the name. | |
| 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. | |
| goodsReturned | No | An ADVISORY hint only: it pre-ticks the reviewer's 'the goods came back into stock' checkbox. It does NOT decide the stock movement — the human does, at approval, and even then only the lines the ORIGINAL invoice actually shipped can come back, up to the quantity it shipped; claiming more is refused rather than posted. Ignored for an allowance (always money-only). | |
| originalDocId | No | against_invoice: the ORIGINAL invoice's id, from search_documents. The server verifies it exists, is an INVOICE and whose it is — it never guesses. | |
| originalDocNumber | No | against_invoice: the printed invoice number, when you have no id. Refused if more than one document carries it — find the right one with search_documents. |