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

# Units

> Manage the physical spaces you let — details, occupancy, financial position, and the full lease-status reference.

**Admin → Units → `/units`**

A unit is the billable physical space: an apartment, a shop, a room, a parking bay. Everything
financial ultimately attaches to a unit through a lease, so unit data quality decides how good your
occupancy, revenue and arrears numbers are.

## What a unit record holds

| Group              | Fields                                                                |
| ------------------ | --------------------------------------------------------------------- |
| **Identity**       | House number, name, block, branch, main unit (for sub-units)          |
| **Classification** | Type, category, classification, occupancy type                        |
| **Physical**       | Size, beds, water meter number                                        |
| **Commercial**     | Is managed, points, notes                                             |
| **Derived**        | Status, active leases, all leases, residents and resident count       |
| **Financial**      | Total invoiced, total paid, total due, prepaid amount, wallet balance |

The financial figures are computed from the ledger, not stored on the unit — they always agree with
the invoices and payments behind them.

<Note>
  **Main unit** links sub-units to a parent (a shop subdivided into stalls; a house with an annex).
  Billing and reporting respect the hierarchy, so a parent's totals include its children.
</Note>

## Adding a unit

<Steps>
  <Step title="Open the units list">
    **Admin → Units → Add.**
  </Step>

  <Step title="Identify it">
    House number or name, and the block it sits in. Use a naming convention and stick to it — "A101"
    and "A 101" and "Apt A101" become three units in a report.
  </Step>

  <Step title="Classify it">
    Type, category and occupancy type. These drive occupancy reporting and which units appear in
    which lists.
  </Step>

  <Step title="Record the physical details">
    Size and beds feed reporting and pricing comparisons. The water meter number links the unit to
    its [smart meter](/guides/utilities-smart-meters).
  </Step>

  <Step title="Set management and ownership">
    Whether the unit is managed by you, and which owner it belongs to. Ownership drives
    [owner statements](/guides/owner-statements).
  </Step>

  <Step title="Save">
    The unit is now selectable when creating a lease.
  </Step>
</Steps>

### Importing units

Use **Admin → Bulk Upload** with the *Units* type to create many units at once from a spreadsheet,
with validation and a per-row outcome. See [Bulk upload](/guides/bulk-upload).

## The unit detail view

Opening a unit gives you the whole picture in one place:

* **Header** — identity, block, type and current status.
* **Financial KPIs** — total invoiced, total paid, total due, prepaid, wallet balance.
* **Residents** — who is currently associated, in which role.
* **Leases** — active and historical, with dates and status.
* **Transactions** — the unit's invoices and payments.
* **Documents** — anything attached to the unit.

## Occupancy

Occupancy is derived from lease status, not typed in. A unit is occupied when it has an active
lease; it becomes available when that lease ends.

Filter the units list by occupancy and lease status to answer the questions that actually come up:

* Which units are vacant right now?
* Which leases end in the next 60 days?
* Which units have an active lease but no recurring charge? (These bill nothing.)

<Warning>
  A unit showing as occupied with no active lease, or vacant with an open lease, means the lease's
  status is wrong — fix the lease, not the unit.
</Warning>

## Full lease-status reference

Leases and units share one lifecycle lookup:

| #  | Status                         | Meaning                                                                  |
| -- | ------------------------------ | ------------------------------------------------------------------------ |
| 1  | **Draft**                      | Being prepared; not yet effective.                                       |
| 2  | **Pending**                    | Awaiting signature, approval, or initial payment/deposit.                |
| 3  | **Active**                     | In force; billing is ongoing.                                            |
| 4  | **Under Notice**               | Still active, but a future vacate or termination notice has been issued. |
| 5  | **Suspended**                  | Temporarily paused — disputes or special conditions.                     |
| 6  | **Defaulted** <sup>TPS</sup>   | Tenant Purchase Scheme contract formally in default.                     |
| 7  | **Repossessed** <sup>TPS</sup> | TPS property repossessed by the owner.                                   |
| 8  | **Ended**                      | Reached its natural end and concluded normally.                          |
| 9  | **Terminated**                 | Ended early — breach, agreement, or enforcement.                         |
| 10 | **Completed** <sup>TPS</sup>   | TPS contract fully completed with ownership transfer.                    |
| 11 | **Expired**                    | End date passed without formal closure or renewal.                       |
| 12 | **Cancelled**                  | Voided before becoming active.                                           |

<Info>
  **TPS** statuses belong to [ownership plan](/guides/tps/overview) workflows. Ordinary leases use
  Draft, Pending, Active, Under Notice, Suspended, Ended, Terminated, Expired and Cancelled.
</Info>

## Views

Units support the standard [view switcher](/getting-started/navigating-the-app):

* **Grid** for filtering and export.
* **Calendar** for date-shaped questions — lease starts and ends plotted per unit, with a legend.

## Editing and retiring units

Edit a unit from its detail page. To take a unit out of service — renovation, sale, demolition —
change its status rather than deleting it. Deleting a unit that has billing history breaks
statements, aging and owner reporting.

## Common problems

| Symptom                                           | Cause and fix                                                                                                     |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Unit not selectable when creating a lease         | Wrong branch, or the unit already has an active lease.                                                            |
| Occupancy figures look inflated                   | Leases in a status that counts as occupied but should not (typically Pending or Expired leases never closed out). |
| Unit financials do not match the tenant statement | Check whether you are reading a parent unit's rolled-up totals.                                                   |
| Two units for the same physical space             | Naming inconsistency at import. Consolidate future leases onto one; leave history alone.                          |

## Next steps

<Columns cols={2}>
  <Card title="Managing leases" icon="file-signature" href="/guides/managing-leases">
    Put a tenancy on the unit.
  </Card>

  <Card title="Organisation & branches" icon="sitemap" href="/guides/organization">
    Blocks, branches and how the hierarchy scopes everything.
  </Card>
</Columns>