# Touching financial records in Zoho without breaking the books This applies across **Books, Invoice, Billing, Expense, Inventory and Payroll**. It is not about how to call the API — the per-service skills have that. It is about what must never happen to a financial record, because accounting mistakes are not bugs you patch: they are restatements, wrong tax returns, and numbers a client already reported. Read this before the first write of any financial task. ## 1. Which organization am I in ```bash zone books org list --toon # every org, its currency and country zone ctx books organization_id= ``` An `organization_id` is a **separate set of books, with its own currency, tax registration and fiscal year**. Posting to the wrong one is not a typo you fix with an update — you have created a real transaction in the wrong country's ledger and must reverse it there and re-enter it here, and both reversals stay visible. Check the org before the first write, every session. The one you want is rarely the one that happens to be in ctx. ## 2. A document's status decides what you may do to it | Status | What it means | What you may do | |---|---|---| | **draft** | not accounting yet | edit freely, delete freely | | **sent** / open | issued to the customer, in the ledger | **do not edit** — reverse it properly | | **partially paid / paid** | money has moved | edit nothing; unapply the payment first | | **void** | cancelled, number retained | nothing; it is history | | **overdue** | sent, past due | same rules as sent | The whole discipline is in the second row. Once a document is sent it has been reported to someone — a customer, a tax authority, a revenue figure. Editing it rewrites history silently. ```bash zone books invoice get --json # read the status BEFORE deciding anything ``` ## 3. Void, delete, credit note and write-off are four different things They are not interchangeable, and picking the wrong one is the most common financial error an agent makes. | Action | Command | What it means | When | |---|---|---|---| | **Void** | `zone books invoice void ` | the document is cancelled, **the number is kept** | issued in error, no payment, no goods delivered | | **Delete** | `zone books invoice delete ` | the document never existed — **leaves a gap in the number sequence** | drafts only | | **Credit note** | `zone books creditnote create` then `apply-invoices` | a new document that reverses value | the customer was correctly billed but is owed a return, discount or correction | | **Write-off** | `zone books invoice writeoff ` | the debt is uncollectable — a **bad-debt expense** | the customer will not pay | A credit note is the correct reversal for a sent invoice. It leaves both documents in the ledger, which is exactly what an auditor expects to see. Write-off is not "cancel". It books an expense and affects the P&L. Do not use it to tidy up a mistake — that overstates both revenue and bad debt. ## 4. Number sequences are legally significant Invoice, credit note and bill numbers must be **unbroken and sequential**. A gap is a question from a tax authority: what was in that gap, and who removed it? This is why `void` exists and why `delete` on a sent document is the wrong instinct. In a VAT-registered entity, deleting an issued invoice can mean the filed return no longer reconciles to the ledger. If a document must not stand: void it, or credit it. Never delete it. ## 5. Money is computed by Zoho, never by you Do not calculate totals, tax or balances and send them. Send the **line items, quantities, rates and tax ids** and let Zoho compute — rounding rules, tax-inclusive pricing, compound and cascading taxes, and per-line discounts all differ per org and per country. ```bash zone books tax list --toon # real tax ids for this org zone books invoice get --json # then read back what Zoho computed ``` A total you computed that differs by 0.01 from Zoho's is not a rounding curiosity: it is a mismatch between the document and the ledger. Never change a tax rate on a posted document. Change it for future documents; correct the past with a credit note. ## 6. Payments are a separate object with their own rules ```bash zone books invoice payments # what is applied to this invoice zone books payment delete # unapply before touching the invoice ``` - An invoice with a payment applied **cannot be deleted or edited** until the payment is unapplied. If a call fails on a paid document, the payment is usually the reason. - **Recording a payment is not reconciling a bank feed.** Matching a bank transaction confirms money actually arrived; recording a payment says it did. Doing one without the other leaves the bank account permanently out of balance. - Refunds attach to a credit note or payment, not to the invoice. ## 7. Journal entries are the escape hatch and the sharpest tool ```bash zone books journal create --data '{...}' zone books journal reverse # the correct undo zone books journal delete # only for an unpublished draft ``` A journal entry writes directly to the general ledger, bypassing every document workflow. It is the right answer for corrections and accruals and the wrong answer for anything a document can express. **Reverse, do not delete.** `reverse` creates the mirroring entry and leaves the audit trail intact, which is what "correcting an entry" means in accounting. Every journal must balance — total debits equal total credits — and Zoho will reject one that does not. Do not "fix" a rejection by adjusting an amount until it balances; the imbalance means the entry is wrong. ## 8. Closed periods and locked transactions ```bash zone books accountingperiod get-transaction-lock --json ``` Books can be locked up to a date, after which the period is closed and reported. **Check the lock before writing to any past-dated transaction.** A write that lands in a closed period either fails or reopens something a bookkeeper deliberately shut. If a correction genuinely belongs in a closed period, that is a human decision by whoever closed it — not something to force. ## 9. Foreign currency ```bash zone books currency list --toon zone books currency rates ``` The exchange rate is fixed at the **transaction date**, not today's rate. Re-pulling a current rate onto a historical document changes reported revenue in the base currency and breaks the reconciliation to the bank. With four orgs in three currencies here, always confirm which currency the org's base is before reading an amount as money. ## 10. Tax and VAT - Tax ids are per org: `zone books tax list`. Never carry an id between orgs. - A tax-registered entity has filing periods. Once a return is filed, the transactions behind it are effectively frozen — corrections go in the next period, via a credit note. - On tax reports, the date filter is the thing people get wrong: filter on **transaction date**, not the created date, or the totals will not match the return. ## 11. Inventory moves the books too In Books and Inventory the stock document and the accounting document are coupled. A shipment or a bill can post to inventory asset and cost of goods sold. So an "inventory fix" is a financial change: the same rules apply, and the reversal is the counter-document, not a delete. ## 12. Before every financial write ```bash zone books org list # 1. right org? zone books invoice get --json # 2. what status is it in? zone books invoice void --dry-run --json # 3. show it, send nothing export ZONE_POLICY='*:GET' # investigate read-only export ZONE_AUDIT=./finance-audit.jsonl # keep the trail ``` Run financial sessions with deletes denied unless a human has explicitly approved one: ```bash zone books invoice void --deny '*:DELETE' ``` **Dry-run every financial write and summarize it in words before asking for a yes.** "This voids invoice INV-000142 for AED 12,500 to Acme, issued 3 March" is consent. A JSON blob is not. ## Errors → what they actually mean | What you see | Meaning | Do | |---|---|---| | cannot delete / edit a sent document | it is in the ledger | void it, or issue a credit note | | an operation fails on a paid invoice | a payment is applied | `invoice payments `, unapply, then retry | | journal rejected as unbalanced | debits ≠ credits | the entry is wrong — do not tune an amount to force it | | a write to a past date fails | the period is locked | `accountingperiod get-transaction-lock`; a human decides | | totals differ from what you computed | you computed money | send line items and let Zoho compute | | "belongs to multiple organizations" | no org in ctx | `zone ctx books organization_id=` — check WHICH org first | | tax report totals do not match the return | filtered on the wrong date | filter on transaction date | ## The rule under all of it Financial records are append-only in spirit. **Corrections are new documents that reference the old ones, never edits that erase them.** If you are about to make the past look different than it did, stop and ask.