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

# Budgets and profitability overview

> Set a ceiling on a project in hours or money, watch spend and forecast against it, get alerted before you overrun, and see the margin on every engagement.

A budget is the ceiling for a project. It is either a number of **hours** or an amount of **money**. Once it is set, the project's Overview shows how much you have used, what the job is forecast to cost, and whether it is still healthy.

## What budgets give you

<CardGroup cols={2}>
  <Card title="A ceiling you can see" icon="gauge">
    A bar showing percent spent against percent complete, so overspending is visible before the invoice.
  </Card>

  <Card title="A forecast" icon="binoculars">
    What the project will cost by the time the remaining estimated work is done – not just what it has cost so far.
  </Card>

  <Card title="Alerts" icon="bell">
    Automatic notifications at 50%, 75%, 90% and 100%, plus a warning when the forecast breaks the budget.
  </Card>

  <Card title="Margin" icon="chart-pie">
    Revenue minus cost, so you know whether the engagement makes money.
  </Card>
</CardGroup>

## Budget vs estimate

These are the two numbers people confuse most.

|             | Estimate                                | Budget                               |
| ----------- | --------------------------------------- | ------------------------------------ |
| Lives on    | A **task**                              | A **project**                        |
| Says        | How long this piece of work should take | The ceiling for the whole engagement |
| Unit        | Hours                                   | Hours or money                       |
| Who sets it | Anyone with `task.reviseEstimate`       | Someone with `budget.manage`         |
| Used for    | Completion percentage and forecasting   | Utilisation, health and alerts       |

They work together. Estimates tell the forecast how much work is left; the budget is what that forecast is measured against. Full detail on [budget vs estimate](/concepts/budget-vs-estimate).

## Where budgets live

There is no top-level Budgets page. A budget belongs to one project, so it lives inside that project.

| Screen                              | What you do there                                            |
| ----------------------------------- | ------------------------------------------------------------ |
| **Project → Settings → Budget**     | Set the budget type, amount, reset schedule and margin floor |
| **Project → Overview → Financials** | See utilisation, forecast, gross profit and health           |
| **Project → Overview → Alerts**     | See and dismiss fired budget alerts                          |
| **Task side panel → Budget cap**    | Add an informational cap to one task                         |
| **Reports**                         | Build profitability and budget reports across projects       |

## The pieces

### Budget kind

Every budget is either `hours` or `money`.

* An **hours** budget carries no currency. It measures logged time.
* A **money** budget carries a currency – your workspace base currency. It measures approved labour cost.

You pick one. See [hours vs money budgets](/budgets/hours-vs-money-budgets).

### Periodicity

A budget either runs once or resets every month.

* **One-time** – a single pool for the life of the project.
* **Monthly** – a recurring retainer. The pool refills at the start of each calendar month, in your workspace timezone.

The **Resets** control only appears when the project's billing method is **Retainer**. See [recurring retainers](/budgets/recurring-retainers).

### Margin floor

An optional percentage between 0 and 100. If the forecast margin falls below it, an alert fires. Leave it blank to skip margin-floor alerts.

### Task caps

An individual task can carry a cap – "this task should not exceed 8 hours". Caps are **informational**. They never reduce the project's budget. See [task-level caps](/budgets/task-level-caps).

## Example

Northwind Studio runs four projects with four different shapes.

| Client           | Project          | Budget                   | Why                                                  |
| ---------------- | ---------------- | ------------------------ | ---------------------------------------------------- |
| Bluebird Coffee  | Website Redesign | \$40,000 money, one-time | A fixed-fee build. The ceiling is a cash number.     |
| Bluebird Coffee  | Monthly Retainer | 40 hours, monthly        | A retainer sells time. The pool refills every month. |
| Harbor Logistics | Mobile App       | 600 hours, one-time      | Billed hourly against a capped scope.                |
| Fenwick Legal    | Brand Refresh    | No budget                | A small job. Not worth tracking a ceiling.           |

A project with no budget still tracks time and still invoices. It shows **No budget set** in the Financials panel, and no utilisation, forecast or health.

## What health means

Once a budget exists, the project shows a health chip.

| Chip            | Colour | When                                                                                                                                                                   |
| --------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **On track**    | Green  | Nothing below is true                                                                                                                                                  |
| **At risk**     | Amber  | Utilisation is 75% or more, or the forecast is at 90% or more of the budget, or there is at least one overdue task, or there are five or more entries pending approval |
| **Over budget** | Red    | The forecast exceeds the budget, or utilisation is 100% or more, or spend leads progress by 25 percentage points or more                                               |

Health is **derived**, never set by hand. You cannot mark a red project green. Fix the underlying number instead.

Red beats amber, and amber beats green.

<Note>
  "Spend leads progress by 25 points" catches the dangerous case early. A project at 60% utilisation and 30% completion is only 60% spent, but it is burning twice as fast as it is delivering.
</Note>

## Plan and app requirements

| Requirement           | Detail                                                                                                                     |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **App**               | Budgets & profitability must be on in **Settings → Apps**. On by default. Requires Projects & tasks **and** Time tracking. |
| **Plan – budgets**    | **Pro**. Setting a project budget needs the `budgets` feature.                                                             |
| **Plan – cost rates** | **Pro**. Setting a cost rate needs the `profitability` feature.                                                            |

Those last two are separate. The `profitability` feature gates exactly one thing: setting a **cost** rate. It is not a blanket lock on margin.

On Free:

* cost, revenue and margin already recorded stay **readable**
* **billing** rates stay free to set
* a new **cost** rate cannot be set, so margin stops being maintained

Who may **see** cost and margin is a capability question – `time.viewCost` and `rate.viewCost` – never a plan question. Keep the two ideas apart. See [plans and features](/concepts/plans-and-features).

## Permissions

| Action                            | Capability                         | Roles that hold it            |
| --------------------------------- | ---------------------------------- | ----------------------------- |
| Set or change a project budget    | `budget.manage`                    | Owner, Admin, Project Manager |
| Add or remove a task cap          | `budget.manage`                    | Owner, Admin, Project Manager |
| Dismiss a budget alert            | – (workspace member)               | Any member of the workspace   |
| See revenue and billable value    | – (workspace member)               | Any member of the workspace   |
| See cost, gross profit and margin | `time.viewCost` or `rate.viewCost` | Owner, Admin                  |

The Budget section in project Settings is **hidden entirely** without `budget.manage`. A Project Manager may legitimately run a project without seeing its money, so the two gates are genuinely different.

Full detail on [budget permissions](/budgets/budget-permissions).

## Common questions

<AccordionGroup>
  <Accordion title="Can a project have both an hours and a money budget?">
    The Budget section holds one budget per project. Pick the unit that matches how you sold the work.
  </Accordion>

  <Accordion title="Do expenses count against a project budget?">
    No. A money budget measures approved labour cost. Expenses are tracked separately on the Expenses source. See [expenses overview](/expenses/overview).
  </Accordion>

  <Accordion title="Does unapproved time count?">
    It depends on the budget kind. A money budget counts **approved** cost only. An hours budget counts **all logged time**, whatever its approval state. See [how budgets work](/budgets/how-budgets-work).
  </Accordion>

  <Accordion title="What happens when a project goes over budget?">
    Nothing is blocked. People keep tracking time. The health chip turns red, an alert fires, and the project managers are emailed with three options: increase the budget, approve the overage, or pause the work.
  </Accordion>

  <Accordion title="Can I set a budget on a client rather than a project?">
    No. A budget belongs to one project. A client with several projects has several budgets, and the client view rolls them up.
  </Accordion>

  <Accordion title="What currency is a money budget in?">
    Your workspace base currency. The Amount field is labelled with it, for example **Total amount (USD)**.
  </Accordion>
</AccordionGroup>

## Troubleshooting

| Problem                                       | Cause and fix                                                                          |
| --------------------------------------------- | -------------------------------------------------------------------------------------- |
| The Budget section is not in project Settings | You lack `budget.manage`, or the Budgets app is off.                                   |
| **Financials** shows **No budget set**        | No budget exists yet, and no approved time has been recorded. Click **Set budget**.    |
| Utilisation stays at 0% on a money budget     | Time has been logged but not approved. A money budget only counts approved cost.       |
| The forecast margin tile is missing           | You lack `time.viewCost` and `rate.viewCost`. Cost tiles are omitted, not blanked.     |
| The **Resets** control is missing             | The project's billing method is not **Retainer**. Change it in project Settings first. |
| A budget change shows an upgrade dialog       | Budgets is a Pro feature.                                                              |

## Related guides

<CardGroup cols={2}>
  <Card title="How budgets work" icon="gears" href="/budgets/how-budgets-work">
    Utilisation, forecast and health in detail.
  </Card>

  <Card title="Set a project budget" icon="pen-to-square" href="/budgets/set-a-project-budget">
    Every field on the Budget form.
  </Card>

  <Card title="Hours vs money budgets" icon="scale-balanced" href="/budgets/hours-vs-money-budgets">
    Which unit to choose, with worked examples.
  </Card>

  <Card title="Budget alerts" icon="bell" href="/budgets/budget-alerts">
    The 50/75/90/100 ladder and who gets told.
  </Card>

  <Card title="Profitability and margin" icon="chart-pie" href="/budgets/profitability-and-margin">
    Revenue minus cost, explained.
  </Card>

  <Card title="Budget vs estimate" icon="ruler" href="/concepts/budget-vs-estimate">
    The distinction to get right first.
  </Card>
</CardGroup>