> ## Documentation Index
> Fetch the complete documentation index at: https://docs.timetracker.in/llms.txt
> Use this file to discover all available pages before exploring further.
# Leave balances
> Understand accrued, used, pending, remaining and available leave, plus negative balances, year-end resets, adjustments and the balance history ledger.
A leave balance answers one question: **how much of this policy does this person
have left?**
Every balance is built from an append-only ledger. Nothing is ever overwritten,
so you can always see how a number got where it is.
## The five figures
| Figure | What it counts |
| ------------- | ------------------------------------------------------------------------------------ |
| **Accrued** | Everything granted – opening balance, accruals, manual adjustments, year-end resets. |
| **Used** | Leave actually consumed by approved requests, minus anything reversed. |
| **Pending** | Requests submitted but not yet decided. A hold, not a spend. |
| **Remaining** | `Accrued − Used` |
| **Available** | `Remaining − Pending` |
**Available** is the number a new request is checked against, not **Remaining**.
Without that, two pending requests could each pass against the same remaining
balance and overdraft it the moment both were approved.
### A worked example
Sarah Lin on `Annual leave`, unit days.
| Event | Accrued | Used | Pending | Remaining | Available |
| ----------------------------------- | ------- | ---- | ------- | --------- | --------- |
| Joins the policy, opening balance 5 | 5 | 0 | 0 | 5 | 5 |
| Six monthly accruals of 2 | 17 | 0 | 0 | 17 | 17 |
| Takes 4 days, approved | 17 | 4 | 0 | 13 | 13 |
| Requests 5 more days, pending | 17 | 4 | 5 | 13 | 8 |
| Requests 3 more days, pending | 17 | 4 | 8 | 13 | 5 |
| First request approved | 17 | 9 | 3 | 8 | 5 |
| Second request rejected | 17 | 9 | 0 | 8 | 8 |
Check the maths at each row: remaining is always accrued minus used, and
available is always remaining minus pending. Notice that **Remaining** does not
move when a request goes pending – only **Available** does.
## Where to see a balance
* The **Request time off** dialog shows **Available** live as you pick dates.
* Your member record has a **Time off** tab with your balances and full
history. Open it from **Settings → Team members** and pick yourself.
* **Time Off → Balance** shows a member-by-policy roster. Needs
`leave.viewOthers`.
* A person's record → **Time off** tab shows one person's balances and ledger.
### The Balance tab
| Column | What it shows |
| ------------- | ----------------------------- |
| **Member** | Avatar and name. |
| **Policy** | Which policy this row is for. |
| **Accrued** | Total granted. |
| **Used** | Total consumed. |
| **Pending** | Currently held. |
| **Remaining** | Accrued minus used. |
One row per member per policy. Search, sort and page like any other table. Each
row has a three-dot menu with **History**, and **Adjust** for holders of
`leave.managePolicy`. An **Adjust balance** button above the table opens the same
dialog with nothing preset.
## Balance history
**History** opens an append-only ledger for that member and policy, newest first.
| Column | What it shows |
| ---------- | ------------------------------------------------------------------ |
| **Kind** | Opening, Accrual, Request, Reversal, Adjustment or Year-end reset. |
| **Amount** | The signed movement, such as `+2` or `-5`. |
| **Date** | The date the movement took effect. |
| **Actor** | Who did it. `System` for movements the accrual engine posted. |
| **Note** | Free text, if any. |
| Kind | Sign | Where it lands |
| ------------------ | -------- | ------------------------------------------- |
| **Opening** | Positive | Accrued |
| **Accrual** | Positive | Accrued |
| **Request** | Negative | Pending while undecided, Used once approved |
| **Reversal** | Positive | Reduces Used |
| **Adjustment** | Either | Accrued |
| **Year-end reset** | Positive | Accrued |
Nothing in the ledger is ever edited or deleted. A correction is a new row, not a
rewrite. That is what makes a balance auditable.
## Adjusting a balance
Use an adjustment for a correction, a bonus grant, a carry-over from another
system, or a deduction agreed outside the request flow.
From **Time Off → Balance**, use the row menu → **Adjust**, or the
**Adjust balance** button. From a person's record, use the **Adjust** control
on their **Time off** tab.
Both are locked when you opened from a specific row.
Positive grants, negative deducts. The placeholder shows `+5 or -3`.
Optional, but say why. The note is the only explanation the ledger will ever
carry.
A toast reports the resulting remaining balance.
The dialog states the effect plainly: *"This adds or removes leave balance and is
recorded as an auditable adjustment. It is reversible via another adjustment –
nothing is permanently deleted."*
An adjustment ignores the negative floor. A `-10` on someone with 2 days left
takes them to `-8`, whatever the policy allows. Check the balance before you
deduct.
Adjusting needs `leave.managePolicy` – Owner and Admin only. Seeing a balance
needs `leave.viewOthers` (or being the person yourself). A manager who can see a
balance still cannot move it.
## Negative balances
A policy decides whether a balance may go below zero.
| Policy setting | Floor | Effect |
| ------------------------------------------------------- | ----- | ----------------------------------------------------- |
| **Allow negative balance** off | `0` | Requests are blocked once available reaches zero. |
| **Allow negative balance** on, **Minimum balance** `-5` | `-5` | Requests are allowed until available would pass `-5`. |
Landing exactly on the floor is allowed. One unit past it is refused, and the
request dialog says *"This request exceeds the negative-balance limit (floor
-5 days)."*
### Worked example
Jonas Bergman on `Sick leave`, negative allowed to `-5`, no accrual, no opening
balance.
| Event | Accrued | Used | Remaining | Available | Allowed? |
| --------------- | ------- | ---- | --------- | --------- | ------------------------- |
| Start | 0 | 0 | 0 | 0 | – |
| Requests 3 days | 0 | 0 | 0 | −3 | Yes, `-3 ≥ -5` |
| Approved | 0 | 3 | −3 | −3 | – |
| Requests 2 more | 0 | 3 | −3 | −5 | Yes, exactly at the floor |
| Approved | 0 | 5 | −5 | −5 | – |
| Requests 1 more | – | – | – | −6 | **No** – past the floor |
## Carry-over and year end
Balances **carry forward**. A positive remaining balance at 31 December is still
there on 1 January. There is no automatic wipe of unused leave.
Two settings change what happens at a year boundary:
| Setting | Where | Effect |
| -------------------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Reset at year end** | Negative balance section of the policy | A **negative** remaining balance is cleared back to zero and a `Year-end reset` row is written. A positive balance is untouched. |
| **Unused balance expires** | Accrual section of the policy | An accrual older than one year is not credited when the engine runs. |
**Reset at year end** only clears negatives. It never caps or removes a positive
balance. If you need a use-it-or-lose-it cap, post a negative adjustment – there
is no automatic clawback of unused positive balance.
## Permissions
| Action | Capability | Roles |
| --------------------------- | ------------------------------- | ----------------------------- |
| See your own balance | `leave.request` | Every working role |
| See other people's balances | `leave.viewOthers` | Owner, Admin, Project Manager |
| See the history ledger | `leave.viewOthers`, or your own | Owner, Admin, Project Manager |
| Adjust a balance | `leave.managePolicy` | Owner, Admin |
## Common questions
You have a request pending. It is held against Available until it is decided.
The roster is only for holders of `leave.viewOthers`. Your own balance shows
in the request dialog and on your member record.
Post the opposite adjustment. The original row stays in the ledger, which is
the point – you can see both.
No. The opening grant is once ever per person and policy.
No. Amounts are stored exactly, so half and quarter days add up precisely.
No row exists until something moves – an opening grant, an accrual, or a
request.
## Troubleshooting
| Problem | What to check |
| ------------------------------------------ | -------------------------------------------------------------------------------------- |
| A balance is not growing | The policy has accrual off, or the Time Off app is switched off, which pauses accrual. |
| An adjustment is refused | An adjustment of zero changes nothing. Use a signed amount such as `+1.5`. |
| "member is not assigned to this policy" | Adjustments only work for people the policy applies to. |
| The negative did not reset in January | **Reset at year end** is off, or the balance was already positive. |
| Two people's numbers do not match a report | Check the ledger. Every movement is there, with who made it. |
## Related guides
How the accrued figure grows.
Negative floors, opening balances and units.
The live Available readout.
How a decision moves the numbers.
Get balances out as CSV or Excel.