> ## 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.
# Allocations
> Apply received money against invoices — manually, in bulk, or with the allocation engine — and reverse it safely.
**Finance → Receivables → Allocations → `/allocations`**
Receiving money and settling a bill are two different events. A payment lands as **cash on the
lease**; an **allocation** is what applies it to specific invoices. Until money is allocated:
* the invoice stays `unpaid` and continues to age;
* the debt still appears in the debt-aging report and can open a collections case;
* the resident's statement shows both a bill and a credit that have not met.
Allocations is its own destination because allocation **runs** are an engine concern, not a
property of a single payment record.
## The two tabs
| Tab | Route | Contents |
| ------------------- | ------------------- | ------------------------------------------------------------------------ |
| **Allocations** | `/allocations/list` | Every allocation: which payment, which invoice, how much, when, by whom. |
| **Allocation Runs** | `/allocations/runs` | The run log of the allocation engine. |
## Allocating manually
Both sides offer the allocation dialog.
The dialog shows the payment, the lease/unit, the available amount, and the candidate invoices
with what will be allocated to each.
Change the amount against any invoice. What is not allocated is shown as **To Wallet** — it
stays as unapplied cash on the lease.
Before you commit: *Will Allocate*, *Will Pay*, *Returns to Wallet*. This is the preview — read
it rather than clicking through it.
The allocation is written, invoice payment statuses update, and the ledger posts.
## The allocation engine
The engine matches unallocated payments to outstanding invoices automatically, using the
organisation's [payment rules](/guides/payment-rules) for ordering (for example oldest-first, or
rent before utilities).
It is **preview-first**:
Runs the match and shows what *would* happen — how many payments, how much would be allocated,
what would be skipped and why. Nothing is written.
Commits the previewed run. The execution is linked to the preview that produced it.
Undoes a run in full. The reverted run and the reverting run are linked to each other.
### Reading the run log
| Column | Meaning |
| ------------------------- | ---------------------------------------------------------------------------- |
| **Run Type** | Preview, execute, or revert. |
| **Mode** | How the run was invoked. |
| **Status** | Outcome of the run. |
| **Payments** | Payments considered. |
| **Allocated** | Payments successfully allocated. |
| **Skipped** | Payments deliberately not allocated (out of scope, no match, guard tripped). |
| **Errors** | Failures. |
| **Amount** | Total value allocated. |
| **Correlation ID** | The id that ties preview, execution and reversal together. |
| **Preview Correlation** | The preview this execution came from. |
| **Reverted Run** | The run this one reversed. |
| **Property** | Branch scope of the run. |
| **Triggered By / Run By** | Whether a person or the scheduler started it, and who. |
| **Started At / Duration** | Timing. |
| **Error** | The failure detail, when there is one. |
An `allocated = 0` run with a high `skipped` count is almost never a bug in the engine — it usually
means the payments in scope had no matching outstanding invoices, or a guard (branch scope, unit
scope) excluded them. Open the run to see the skip reasons.
### Scheduled allocation
The engine can run on a schedule. It works organisation by organisation in rotation, with
per-branch limits, so a large branch cannot starve the others of processing. The job is
individually switchable and defaults to off outside production.
## Reversing an allocation
Reversal is a first-class operation, not a delete:
* Reversing an **allocation** returns the money to the lease's wallet and re-opens the invoice
balance.
* Reversing a **run** reverses every allocation the run created.
* Both are recorded, linked and auditable.
Never de-allocate by deleting rows or editing amounts directly. The allocation ledger is what the
invoice balance, the wallet figure and the general ledger all read; a manual edit produces figures
that disagree with each other and are very hard to unpick later.
## Wallet, prepaid, and what can be netted
Three figures are easy to confuse:
| Figure | What it is | Nettable? |
| ------------------ | --------------------------------------------- | ------------------------------------------------------ |
| **Wallet amount** | Cash received on the lease, not yet allocated | **Yes** — this is genuinely unapplied money |
| **Prepaid amount** | The already-settled portion of an invoice | **No** — it is already inside the invoice's due amount |
| **Due amount** | What remains payable on an invoice | — |
Prepaid attributes to the **invoice's** unit; wallet attributes to the **payment's** unit. On a
multi-unit tenant this distinction decides which unit's balance moves.
## Over-allocation
Allocating more than an invoice is worth, or more than a payment holds, is guarded server-side. If
you see a negative wallet balance on a lease, it is a symptom of an unguarded historical
allocation, not a legitimate state — raise it rather than trying to correct it by hand.
## Troubleshooting
| Symptom | Cause |
| ----------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Payment received but invoice still unpaid | Not allocated yet. |
| Tenant statement shows a credit and a debt at the same time | Same cause — allocate. |
| Allocation dialog shows no candidate invoices | The invoice is still `draft`, or belongs to a different lease/branch than the payment. |
| Engine run allocated nothing | Check skip reasons in the run detail. |
| Balance changed after a reversal in an unexpected direction | Reversal returns money to wallet; the invoice balance goes back up. That is correct. |