# Set a budget

URL: /systems/finance/set-a-budget · Id: `guide:set-a-budget`

> Say "set a budget for marketing" and get a Budget read against real spend, a monthly review with a forecast, and an alert when it runs over.

Set how much one account may spend or earn in a month, and read it against what moved.

Needs: [Open a bank account](/systems/finance/open-a-bank-account)

**Before it runs**

- You leave the chat: Never: it all happens in the chat.

## What you get
- 1 Budget per spending category and month, compared with actual spend as money moves (Budget)
- 1 monthly review of spend against every Budget, with a six-month forecast (Process)
- 1 message when an account runs over its Budget by the alert share you set (Message)
- 1 Approval from you before any Budget changes (Approval)

## Your agent does
**For agents**

- Guide: `guide:set-a-budget`, status `beta`. Page: [/systems/finance/set-a-budget.md](/systems/finance/set-a-budget.md).
- Approval: none. Run it when the founder asks.
- Leaves the chat: never.
- Needs first: [Open a bank account](/systems/finance/open-a-bank-account).
- Run: call the steps in order, each through the API, SDK, CLI or MCP tab below; a later step passes the `$id` an earlier one returns. Each value marked example is the sample business’s: pass the founder’s own.

| Step | Verb | Inputs (type, required, this guide’s value) | Returns |
| --- | --- | --- | --- |
| 1 | [`Budget.create`](/business/nouns/budget/create) (`verb:Budget.create`) | `account` string, required: example `"expense.ads"`; `period` Period (an id), required: example `"period_2026_11"`; `amount` money, required: example `{"amount":500,"currency":"USD"}` | `budget` Budget |

Returns: the last call answers with `budget` and its `action`, whose `status` is `done`, `pending` (waiting on an Approval or a Worker), `failed`, `canceled` or `refused`:

```json
{
  "api": "https://api.sb/leaseline.app",
  "budget": {
    "$id": "https://api.sb/leaseline.app/budgets/budget_1",
    "$type": "Budget",
    "account": "expense.ads",
    "period": "period_2026_11",
    "amount": {
      "amount": 500,
      "currency": "USD"
    }
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/action_1",
    "operation": "Budget.create",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/action_1"
  }
}
```

Next: offer “Make it $800 from next month”, or “Tell me when any budget runs 10% over”.

Calls: `Budget.create`

Ask:

```text
Set a budget for marketing.
Cap what we spend on software at $300 a month.
Are we on budget?
```

API:

```bash
# Budget.create
curl -X POST https://api.sb/leaseline.app/budgets \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"account":"expense.ads","period":"period_2026_11","amount":{"amount":500,"currency":"USD"}}'
```

SDK:

```ts
import { $ } from 'startup-builder'

await $.Budget.create({ account: 'expense.ads', period: 'period_2026_11', amount: { amount: 500, currency: 'USD' } })
```

CLI:

```bash
npx startup-builder do Budget.create --json '{"account":"expense.ads","period":"period_2026_11","amount":{"amount":500,"currency":"USD"}}'
```

MCP:

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Budget.create({ account: 'expense.ads', period: 'period_2026_11', amount: { amount: 500, currency: 'USD' } })"
  }
}
```

## Change it
- Make it $800 from next month.
- Tell me when any budget runs 10% over.
- Hold the ads card when the ads budget runs out.
- Show spend against budget every Monday.

## Under the hood
- Systems: [Ledger](/systems/ledger), [Treasury](/systems/treasury), [Spend management](/systems/spend)
- Nouns: [Budget](/business/nouns/budget), [Entry](/business/nouns/entry), [Period](/business/nouns/period), [Forecast](/business/nouns/forecast)
- Events: `Budget.created`, [`Period.closed`](/business/events/Period.closed)

A [Budget](/business/nouns/budget) plans one account in the chart of accounts for one [Period](/business/nouns/period), such as `expense.ads` for one month. Its actual is computed from [Entries](/business/nouns/entry) as each [Transaction](/business/nouns/transaction) reconciles, so it is never a month behind.

When a Period closes, the [Budget](/workflows/processes/budget) [Process](/business/nouns/process) compares spend with every Budget, forecasts six months ahead and proposes next month's numbers. Any change waits for your yes.

A Budget reports; a [Limit](/business/nouns/limit) stops. To make an agent stop at the number, put the same amount on its [Card](/business/nouns/card) or [Mandate](/business/nouns/mandate), as the [card with a limit](/systems/finance/issue-a-card-with-a-limit) guide does.