# Budgets

> Create budgets, track spending against plans, and generate forecasts.

- **Category:** Guides
- HTML version: https://www.ondayzero.com/docs/guides/budgets
- All guides: https://www.ondayzero.com/docs/guides/index.md
- Endpoint catalog: https://www.ondayzero.com/docs/reference/index.md

---

# Budgets

Budgets let you set spending targets by account and compare actual performance against plan. This feature requires the **CFO Suite** add-on.

## Create a Budget

```bash
curl -X POST "https://api.ondayzero.com/api/v1/budgets" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "FY2026 Operating Budget",
    "fiscal_year": 2026,
    "start_date": "2026-01-01",
    "end_date": "2026-12-31",
    "period_type": "monthly",
    "description": "Board-approved operating plan"
  }'
```

`name`, `fiscal_year`, `start_date` and `end_date` are required. `period_type` is `monthly` (default), `quarterly` or `annual`. A new budget starts as a `draft`.

## Add Budget Lines

Each line ties a ledger account to twelve monthly amounts (in cents):

```bash
curl -X POST "https://api.ondayzero.com/api/v1/budgets/{budget_id}/lines" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "ledger_id": "EXPENSE_LEDGER_UUID",
    "jan_amount": 500000,
    "feb_amount": 500000,
    "mar_amount": 500000,
    "apr_amount": 550000,
    "may_amount": 550000,
    "jun_amount": 550000,
    "jul_amount": 600000,
    "aug_amount": 600000,
    "sep_amount": 600000,
    "oct_amount": 650000,
    "nov_amount": 650000,
    "dec_amount": 650000,
    "notes": "Includes planned Q3 headcount"
  }'
```

> Amounts are in cents. `500000` = $5,000.00 for that month. Months you omit default to `0`.

`GET /api/v1/budgets/{budget_id}/lines` lists lines; `PATCH` / `DELETE /api/v1/budgets/{budget_id}/lines/{line_id}` change or remove one. A ledger can appear on a budget only once (`VALIDATION_085`), and lines can only be added or edited while the budget is a `draft` (`VALIDATION_084` / `VALIDATION_086`) — copy an active budget to revise it.

## List Budgets

```bash
curl "https://api.ondayzero.com/api/v1/budgets?fiscal_year=2026&status=active" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"
```

### Filter Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `status` | string | `draft`, `active`, `closed` |
| `fiscal_year` | integer | Filter by year (e.g., 2026) |
| `search` | string | Match on budget name |

Plus the standard [pagination](/docs/guides/pagination) parameters.

## Activate a Budget

Only one budget is active at a time. Activating a draft makes it the working budget for variance reporting and deactivates the previous one:

```bash
curl -X POST "https://api.ondayzero.com/api/v1/budgets/{budget_id}/activate" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"
```

`PATCH /api/v1/budgets/{budget_id}` edits `name`, `description`, `notes` and the date range; `DELETE` removes a budget.

## Budget vs. Actual

Compare budgeted amounts to actual spending for a date range:

```bash
curl "https://api.ondayzero.com/api/v1/budgets/{budget_id}/vs-actual?start_date=2026-04-01&end_date=2026-06-30" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"
```

Returns line-by-line comparisons with variance amounts and percentage of budget consumed. Both dates are required.

## Forecasts

Generate spending forecasts from historical actuals:

```bash
curl -X POST "https://api.ondayzero.com/api/v1/budgets/forecast" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "seasonal",
    "lookback_months": 24,
    "forecast_months": 12,
    "growth_rate_percent": 5,
    "use_seasonality": true,
    "include_cash_flow": true
  }'
```

All fields are optional. `method` is `linear_trend` (default), `moving_average`, `seasonal` or `year_over_year`; `lookback_months` and `forecast_months` default to `12`. Save a reusable set of parameters with `POST /api/v1/budgets/forecast/configs` and list them with `GET /api/v1/budgets/forecast/configs`.

## Copy a Budget

Duplicate an existing budget — lines included — as the starting point for the next period, optionally scaling every amount:

```bash
curl -X POST "https://api.ondayzero.com/api/v1/budgets/{budget_id}/copy" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "FY2027 Operating Budget",
    "fiscal_year": 2027,
    "start_date": "2027-01-01",
    "end_date": "2027-12-31",
    "adjustment_percent": 5
  }'
```

`name`, `fiscal_year`, `start_date` and `end_date` are required; `adjustment_percent` applies to all amounts (`5` = +5%, `-10` = −10%).