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

# Set a project budget

> Add or change a budget on a TimeTracker project: choose hours or money, enter the amount, set a monthly reset for retainers, and add a margin floor alert.

To set a budget, open the project, go to **Settings**, find the **Budget** card, choose a budget type, enter an amount and click **Set budget**.

## Before you start

You need:

* the `budget.manage` capability – Owner, Admin or Project Manager
* the **Budgets & profitability** app switched on
* the **Pro** plan

If you cannot see a **Budget** card in project Settings, one of those three is missing.

## How to set a budget

<Steps>
  <Step title="Open the project's settings">
    Go to **Projects**, open the project, then click **Settings**.
  </Step>

  <Step title="Find the Budget card">
    It is described as "The target this project is measured against. Overview shows spend, forecast and health once a budget is set."
  </Step>

  <Step title="Choose the budget type">
    Pick **Total hours** or **Total money**. This decides what the budget measures.
  </Step>

  <Step title="Enter the amount">
    The field is labelled **Total hours** or **Total amount (USD)** depending on your choice. Enter a positive number.
  </Step>

  <Step title="Set the reset schedule">
    The **Resets** control only appears on a retainer project. Choose **One-time** or **Monthly**.
  </Step>

  <Step title="Add a margin floor (optional)">
    Under **Alert if margin falls below**, enter a percentage between 0 and 100. Leave it blank to skip margin-floor alerts.
  </Step>

  <Step title="Save">
    Click **Set budget**. Once a budget exists the button reads **Save budget**. A toast confirms **Budget saved.**
  </Step>
</Steps>

## Every field on the form

| Field                                     | Control                            | Required                  | Notes                                                                               |
| ----------------------------------------- | ---------------------------------- | ------------------------- | ----------------------------------------------------------------------------------- |
| **Budget type**                           | Dropdown: Total hours, Total money | Yes                       | Defaults to **Total money**                                                         |
| **Total hours** or **Total amount (USD)** | Text, decimal keypad               | Yes                       | Must be greater than zero. Placeholder `e.g. 120` for hours, `e.g. 10000` for money |
| **Resets**                                | Dropdown: One-time, Monthly        | Only on retainer projects | Defaults to **One-time**                                                            |
| **Alert if margin falls below**           | Number, 0 to 100                   | No                        | Placeholder `%`. Blank means no margin-floor alert                                  |
| **Task & section caps**                   | Read-only list                     | –                         | Only shown when caps exist                                                          |

### Budget type

* **Total hours** measures every hour logged against the project, whatever its approval state.
* **Total money** measures approved labour cost, in your workspace base currency.

An hours budget never carries a currency. A money budget always does, and it is always the workspace base currency – the field label tells you which, for example **Total amount (USD)**.

See [hours vs money budgets](/budgets/hours-vs-money-budgets) for how to choose.

### Resets

The **Resets** dropdown only appears when the project's **Billing method** is set to **Retainer**. Everything else is one-time.

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

The helper text under the control says so: "A monthly retainer resets its budget at the start of each calendar month."

To turn a project into a retainer, change **Billing method** in the same Settings screen and save that first. The Budget card reads the **saved** billing method, so an unsaved switch does not reveal the control.

See [recurring retainers](/budgets/recurring-retainers).

### Alert if margin falls below

An optional margin floor, as a percentage from 0 to 100.

When set, an alert fires if the project's forecast margin drops below it. Leave it blank and no margin-floor alert can ever fire on this project.

A value outside 0 to 100 is rejected.

<Tip>
  Set the floor to the margin you actually need to stay in business, not the one you hope for. A floor of 40% on a project you have sold at 45% will alert on almost any slippage, which trains people to ignore it.
</Tip>

## Changing a budget

Setting a budget on a project that already has one **replaces** it. There is never a second budget on the same project.

When you change the amount:

* utilisation recalculates immediately against the new ceiling
* health recalculates
* **already-fired alerts do not re-fire**, because each rung fires once per project

That last point catches people out. If a project crossed 90% of a $10,000 budget and you raise the budget to $20,000, the 90% alert has already fired and will not fire again on this budget's pool. See [budget alerts](/budgets/budget-alerts).

## Example

Northwind Studio sets up three of its four projects.

<Tabs>
  <Tab title="Bluebird Website Redesign">
    A fixed-fee build sold at \$40,000.

    | Field                       | Value                                   |
    | --------------------------- | --------------------------------------- |
    | Budget type                 | **Total money**                         |
    | Total amount (USD)          | `40000`                                 |
    | Resets                      | Not shown – billing method is Fixed fee |
    | Alert if margin falls below | `35`                                    |

    Priya clicks **Set budget**. The Overview now shows a budget bar, and an alert fires if forecast margin drops under 35%.
  </Tab>

  <Tab title="Harbor Logistics Mobile App">
    An hourly build with a capped scope of 600 hours.

    | Field                       | Value                                |
    | --------------------------- | ------------------------------------ |
    | Budget type                 | **Total hours**                      |
    | Total hours                 | `600`                                |
    | Resets                      | Not shown – billing method is Hourly |
    | Alert if margin falls below | blank                                |

    Alerts fire at 300, 450, 540 and 600 hours logged.
  </Tab>

  <Tab title="Bluebird Monthly Retainer">
    40 hours a month, ongoing.

    | Field                       | Value                      |
    | --------------------------- | -------------------------- |
    | Billing method              | **Retainer** – saved first |
    | Budget type                 | **Total hours**            |
    | Total hours                 | `40`                       |
    | Resets                      | **Monthly**                |
    | Alert if margin falls below | blank                      |

    Every month the pool refills and the alert ladder re-arms.
  </Tab>
</Tabs>

Fenwick Legal – Brand Refresh gets no budget at all. It is a small job and the Financials panel reads **No budget set**.

## The Task & section caps list

If any task on the project carries a cap, the Budget card lists them under **Task & section caps**, read-only.

Each row shows the task name and the cap amount with its unit – `8h` for hours, `500 USD` for money.

The helper text is explicit: "Informational only – they don't reduce this project's budget. Add or remove a cap on the task itself."

Caps are added and removed on the task, never here. One writer per concern. See [task-level caps](/budgets/task-level-caps).

## What happens next

Once the budget saves:

1. The project's **Overview → Financials** panel replaces **No budget set** with the budget bar and tiles.
2. Utilisation, forecast and health start being calculated.
3. The alert ladder arms at 50%, 75%, 90% and 100%.
4. The project appears with a health colour anywhere projects are listed.
5. The change is recorded in the workspace audit trail.

## Permissions

| Action                   | Capability                          | Roles that hold it                   |
| ------------------------ | ----------------------------------- | ------------------------------------ |
| See the Budget card      | `budget.manage`                     | Owner, Admin, Project Manager        |
| Set or change a budget   | `budget.manage` + `budgets` feature | Owner, Admin, Project Manager on Pro |
| See the Financials panel | – (workspace member)                | Any member                           |

The Budget card is **hidden entirely** without `budget.manage`, not shown as disabled. Project Settings as a whole is a `project.manage` surface, so a manager can administer a project without seeing its money.

The Budget card saves through its own button rather than the surrounding **Save changes** button. A different mutation under a different capability must not ride along with a general project save.

## Common questions

<AccordionGroup>
  <Accordion title="Can I set a budget in a currency other than my workspace base?">
    No. A money budget is always denominated in your workspace base currency. That keeps every project's utilisation comparable.
  </Accordion>

  <Accordion title="Can a project have two budgets?">
    No. Saving again replaces the existing budget rather than adding a second one.
  </Accordion>

  <Accordion title="Where is the Resets dropdown?">
    It only appears when the project's saved billing method is **Retainer**. Change the billing method, save it, then reopen the Budget card.
  </Accordion>

  <Accordion title="Can I remove a budget once it is set?">
    The Budget card has no delete action. To stop measuring against a ceiling in practice, raise the amount to something the project cannot reach – but the honest move is usually to set the right number.
  </Accordion>

  <Accordion title="Does setting a budget change any historical time entries?">
    No. It only changes what those entries are measured against. No cost, rate or entry is rewritten.
  </Accordion>

  <Accordion title="Should the budget match the sum of my task estimates?">
    Not necessarily. Estimates are how long the work should take. The budget is what you sold. A budget below the estimate total is a useful early signal that the job is underpriced.
  </Accordion>
</AccordionGroup>

## Troubleshooting

| Message or problem                                               | Cause and fix                                                                                     |
| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| No **Budget** card in project Settings                           | You lack `budget.manage`, or the Budgets app is off.                                              |
| **We couldn't save the budget. Check the amount and try again.** | The amount is blank, zero, negative or not a number.                                              |
| An upgrade dialog appears on save                                | Budgets is a Pro feature.                                                                         |
| **Set budget** is disabled                                       | The amount field is empty.                                                                        |
| The margin floor is rejected                                     | It must be between 0 and 100.                                                                     |
| The budget saved but Overview still shows **No budget set**      | Reload the project Overview. If it persists, check you saved on the same project you are viewing. |
| Raising the budget did not re-arm alerts                         | Correct. Each rung fires once. See [budget alerts](/budgets/budget-alerts).                       |

## Related guides

<CardGroup cols={2}>
  <Card title="How budgets work" icon="gears" href="/budgets/how-budgets-work">
    What the budget is measured against.
  </Card>

  <Card title="Hours vs money budgets" icon="scale-balanced" href="/budgets/hours-vs-money-budgets">
    Choosing the right unit.
  </Card>

  <Card title="Recurring retainers" icon="rotate" href="/budgets/recurring-retainers">
    Setting a budget that refills monthly.
  </Card>

  <Card title="Task-level caps" icon="ruler-horizontal" href="/budgets/task-level-caps">
    The read-only list on this card.
  </Card>

  <Card title="Budget alerts" icon="bell" href="/budgets/budget-alerts">
    What the ladder fires and when.
  </Card>

  <Card title="Budget permissions" icon="lock" href="/budgets/budget-permissions">
    Who may set a budget.
  </Card>
</CardGroup>