> ## 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.

# Utilities and smart meters

> Run utility billing end to end — manual readings, smart meters, consumption, tariffs, billing runs and arrears enforcement.

**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

| Surface                         | Use it for                                                                                            |
| ------------------------------- | ----------------------------------------------------------------------------------------------------- |
| **Utilities** (`/utilities`)    | Utility accounts and manual readings per unit and period.                                             |
| **Smart Meters / IoT** (`/iot`) | Connected meters: polling, consumption, tariffs, billing runs, valve control and vendor integrations. |

## 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

<Steps>
  <Step title="Set up meters">
    Assign meters to units, with vendor credentials configured. See
    [Smart meters setup](/guides/iot-smart-meters-setup-process).
  </Step>

  <Step title="Configure tariffs">
    The rate structure that converts consumption to money. See
    [Tariffs](/guides/iot-tariffs-process).
  </Step>

  <Step title="Collect readings">
    Poll meters, or enter readings manually. Check for stale, missing or outlier values before
    going further. See [Meter readings](/guides/iot-meter-readings-process).
  </Step>

  <Step title="Derive consumption">
    The difference between readings, after quality checks. Fix reading problems here, not after
    invoices exist. See [Consumption](/guides/iot-consumption-process).
  </Step>

  <Step title="Run billing">
    Turn the period's consumption into invoices. See
    [Billing runs](/guides/iot-billing-runs-process) and
    [Billing run items](/guides/iot-billing-run-items-process).
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Warning>
  Never run billing over a period with unresolved reading quality issues. An invoice built on an
  outlier reading is a credit note, a tenant dispute and a lost afternoon.
</Warning>

## Monitoring

| Surface                                              | Watch for                                                 |
| ---------------------------------------------------- | --------------------------------------------------------- |
| [Poll failures](/guides/iot-poll-failures-process)   | Meters that stopped reporting.                            |
| [Webhook events](/guides/iot-webhook-events-process) | Inbound vendor events and their processing.               |
| [Vendors](/guides/iot-vendors-process)               | Credential and integration health per vendor.             |
| [Valve commands](/guides/iot-valve-commands-process) | Disconnect and reconnect instructions and their outcomes. |

## 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.

<Note>
  [Collections](/guides/collections/strategies) can hand a case to IoT enforcement as a ladder step,
  but it never drives valves itself — the IoT engine owns that state machine, and the collections
  case mirrors its events read-only.
</Note>

## Utilities without smart meters

The manual path is the same cycle without the polling:

<Steps>
  <Step title="Record the reading">
    Enter the current reading per unit and period; the previous reading is already held.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Bill">
    Consumption is priced by tariff and billed as an invoice line against the lease's utility
    service type.
  </Step>
</Steps>

Readings can also be imported in bulk — **Admin → Bulk Upload** with the *Utility Readings* type.
See [Bulk upload](/guides/bulk-upload).

## Common problems

| Symptom                                | Cause                                                                                    |
| -------------------------------------- | ---------------------------------------------------------------------------------------- |
| No new readings                        | Vendor credentials, meter mapping, or the meter is inactive. Check poll failures.        |
| Consumption looks impossible           | Reading outlier, meter replaced without a baseline, or meter assigned to the wrong unit. |
| Billing run produced nothing           | No consumption for the period, or no tariff configured.                                  |
| Tenant billed for another unit's water | Meter-to-unit assignment. Fix the assignment, then credit the wrong invoice.             |
| Disconnect did not happen              | Shadow mode — the action was staged for confirmation, not executed.                      |

## Next steps

<Columns cols={2}>
  <Card title="IoT playbooks" icon="list-check" href="/guides/iot-smart-meters-setup-process">
    Step-by-step procedures for each stage of the cycle.
  </Card>

  <Card title="Invoices" icon="file-invoice" href="/guides/invoices-and-payments">
    What a billing run produces.
  </Card>
</Columns>