Utilities and smart meters

Operations → Utilities → /utilities · Operations → Smart Meters → /iot

Utilities are billed from consumption: a reading is taken, consumption is derived, a tariff converts it to money, and a billing run turns it into invoices. Whether the reading comes from a person with a clipboard or a connected meter, the rest of the chain is the same.

The two surfaces

The IoT workspace

The smart-meter dashboard is built around the operational cycle rather than around database tables. It shows:

• a health banner — whether polling, consumption and billing are currently healthy;
• workspace cards for each stage of the cycle, with the guided playbook for that stage;
• shortcuts into the tab where the work is done.

Each stage has its own guide — the IoT playbooks in the sidebar. They are written as procedures, not reference: what to do, in what order, and how to tell you are done.

The utility billing cycle

1. Set up meters

   Assign meters to units, with vendor credentials configured. See Smart meters setup.

2. Configure tariffs

   The rate structure that converts consumption to money. See Tariffs.

3. Collect readings

   Poll meters, or enter readings manually. Check for stale, missing or outlier values before going further. See Meter readings.

4. Derive consumption

   The difference between readings, after quality checks. Fix reading problems here, not after invoices exist. See Consumption.

5. Run billing

   Turn the period's consumption into invoices. See Billing runs and Billing run items.

6. Review run items before posting

   Per-unit items are inspectable before and after posting. A bad tariff or a misassigned meter is obvious here and expensive later.

Monitoring

Arrears enforcement

Where enabled, unpaid utility balances can drive an enforcement ladder:

warn → warn again → disconnect → (payment) → reconnect

The engine holds its own safety invariants: both warnings must be provably sent, a grace period must elapse, and the balance is re-checked immediately before any disconnect. It defaults to shadow mode, staging actions for a human to confirm rather than acting alone.

Enforcement creates real invoices for any reconnection charges, so the money side flows through normal billing rather than a side channel.

Utilities without smart meters

The manual path is the same cycle without the polling:

1. Record the reading

   Enter the current reading per unit and period; the previous reading is already held.

2. Check consumption

   A consumption figure far outside the unit's history is usually a transcription error, a meter rollover, or a leak — all worth catching before billing.

3. Bill

   Consumption is priced by tariff and billed as an invoice line against the lease's utility service type.

Readings can also be imported in bulk — Admin → Bulk Upload with the Utility Readings type. See Bulk upload.

Reading the readings board

The meter-type strip at the top of the board picks which pricing rule you are looking at, not which service type — a property with Water B1 / Water B2 / Water B6 has three rules on one service type. Its All meters tab shows every one of them at once, and is where the board now opens. Before it existed you could only ever see one rule's meters at a time, which made a property's water look like a fraction of itself.

The readings chart beside it is drawn from the readings actually recorded for the months you are looking at. Where no month has loaded it says so rather than drawing a flat line.

A reading that consumed nothing is not billed

Where the current and previous readings are equal, the row is skipped instead of becoming a zero invoice. Equal readings are nearly always a mapping mistake — one month's column read as both — and the old behaviour produced an empty KES 0.00 invoice with no lines on it while the upload reported success.

An upload now names the readings it could not bill and why, so a partial run is answerable without opening the database. Unit codes typed with a space in them match the unit they mean, and a per-row date override is honoured.

Common problems

Next steps