Documentation Index
Fetch the complete documentation index at: https://docs.nyumbazetu.com/llms.txt
Use this file to discover all available pages before exploring further.
Accounting and posting
This guide explains how Nyumba Zetu turns day-to-day property-management work—tenant billing, collections, expenses, and related flows—into double-entry accounting in your ledger. It is written for operators and finance users; it is not a full accounting standards manual.What this covers
Your organization’s books reflect what happened in the product: posted invoices, money received, payments applied to invoices, expenses, recharges to tenants, tax and retention movements, and more. Each qualifying business action can produce a journal entry (debits and credits that balance) so reports such as trial balance and P&L trace back to real activity. Nyumba Zetu also supports owner and landlord reporting (statements, amounts due to owners). The company ledger described here is the property manager’s operational accounting; owner splits and trust-style flows may use additional allocation logic depending on your setup—see Owners and landlords and Reports.Core principles
- Double entry: Every journal balances: total debits equal total credits for that entry.
- Audit trail: Journals record the financial effect of business events with references back to the source (for example an invoice or payment).
- Accounting periods: Posting is allowed only into open periods. You cannot post into a closed (or locked) period; period controls protect reported numbers.
- Immutability: Posted journals are not edited in place. Corrections use the product’s supported paths—such as credit notes, refunds, or other adjustments—so the history stays clear.
- Idempotent posting: The same logical event should not create duplicate journals. The system uses a deterministic posting key so duplicate processing returns the existing journal instead of posting again.
Void, write-offs, invoice edits, and multi-part journals
- Void — When an issued invoice is voided, the business document is nullified. In the ledger, that typically means reversing the invoice-originating journals (the receivable/revenue recognition from the invoice), following your policy — not the same as a payment or allocation entry.
- Write-off — When a balance is written off as uncollectable, accounting usually records bad debt (or similar) while preserving the invoice history for audit. That is a different meaning from void: it does not simply “delete” the invoice posting in the same way as a void workflow.
- Invoice edits after posting — If an invoice was already posted and you change amounts or lines that affect recognition, corrections use reversal and repost of the invoice journals (not in-place edits). Payment and allocation journals stay driven by payment flows.
- Reconcile before you finalize — After reposting an invoice, finance processes should ensure the invoice balance still matches allocations and the subledger before treating the new posting as complete.
- Several journals per invoice — Some setups post more than one journal for a single invoice (for example tax or segment splits). Reports and support tools should look at all related journal rows (source and posting keys), not a single “one id” shortcut on the invoice.
How posting runs
When you record an action that affects the ledger (for example posting an invoice or receiving a payment), the application emits a domain event. A background accounting consumer picks up that event, selects the correct posting action and handler, builds journal lines from the event payload (a snapshot of the data), and writes one journal through a single posting service. That keeps the ledger consistent and avoids double-counting when the same event is delivered more than once. Chart of accounts (COA): Accounts are resolved by code for your organization (for example cash, receivables, revenue, VAT). Your administrator maintains the COA in settings; postings hit those accounts rather than hard-coded numeric IDs in application code. Service types: For invoices (and similar), line items often map to service types so revenue and tax post to the right income and liability accounts when configured.Posting rules in Nyumba Zetu
In this product, “posting rules” means:- Posting actions — A catalog of allowed actions (for example invoice post, payment received, expense post). Each action is valid only for certain source types (invoice, payment, expense, and so on).
- Handlers — For each event type, a handler knows how to build balanced lines from the outbox payload (the snapshot shipped with the event), including which accounts to use.
- COA resolution — Accounts are looked up by account code per organization so your chart stays data-driven.
Events and typical journal patterns
The table below lists implemented flows that reach the accounting consumer. Wording is simplified; actual accounts depend on your COA and configuration.| Event (business meaning) | Typical journal pattern (summary) |
|---|---|
invoice.posted — Tenant invoice is posted | Dr Accounts receivable · Cr Revenue (by line/service type) and Cr VAT output where applicable |
payment.received — Customer payment recorded | Dr Cash (bank/M-Pesa account mapped from the payment) · Cr Unapplied receipts (liability until allocated) |
payment.allocated — Payment applied to invoices | Dr Unapplied receipts · Cr Accounts receivable (per allocation amounts) |
expense.posted — Expense approved/posted | Dr Expense / VAT input (by line) · Cr Accounts payable |
expense.payment_recorded — Vendor payment settled | Dr Accounts payable · Cr Cash (and optionally withholding/retention lines when amounts apply) |
tenant_recharge.created — Recharge to tenant (e.g. recoverable cost) | Dr Tenant receivable (recharge) · Cr Due to landlord / owner payable |
wht.remitted — Withholding tax remitted | Dr Withholding tax payable · Cr Cash |
retention.released — Retention released to vendor | Dr Retention payable · Cr Cash |
credit_note.posted — Credit note posted | Dr Revenue / Dr VAT output (reversal of recognition) · Cr Accounts receivable |
refund.issued — Refund to tenant | Dr Unapplied receipts · Cr Cash |
coa.updated — Chart of accounts changed | No journal — refreshes cached account lookups only |
invoice.posted or payment.received. The exact posting action codes stored on the journal are internal identifiers used for validation and reporting.
Some event types may be reserved in configuration for future use (for example vendor credits) but not yet wired to a posting handler. Rely on the flows above for live behavior.
Property management in practice
Tenant billing
When an invoice is posted, the system recognizes receivables and revenue (and output VAT where lines are taxable). That matches the accrual idea: revenue and tax are recorded when the invoice is posted, not only when cash is received.Collections
Payment received first increases cash and unapplied receipts (money received but not yet matched to specific invoices). When you allocate the payment to invoices, unapplied receipts move to accounts receivable, reducing what the tenant still owes on those invoices. This two-step pattern matches many receivables workflows.Expenses and payables
Posted expenses recognize cost and VAT input where applicable, with a credit to accounts payable. When you pay the vendor, payables and cash settle the obligation; withholding or retention may split the credit if your process includes them.Recharges, WHT, and retention
Tenant recharges bill the tenant (receivable) while crediting amounts due to the landlord when that is how your org books recoveries. WHT remittance and retention release move balances from liability accounts to cash when you pay tax authorities or release withheld amounts.Owners and landlords
For owner statements, fees, and payouts, your process may combine ledger balances with allocation rules (how rent and fees split between manager and owner). Those business rules sit alongside the company journal; see Owners and landlords and Reports for where to run statements and period reports.Where to work in the app
- Invoices and payments — Issue invoices and record payments.
- Payments (receive / pay) — Receipts and disbursements.
- Expenses — Vendor bills and payments.
- Adjustments — Credit notes, debit notes, and similar corrections.
- Reports — Trial balance, aging, and financial reports.
- Owners and landlords — Owners, contracts, and owner-facing reporting.