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 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%).