Create a project budget

​

Starts tracking a budget on a project you already have. A project has at most one budget, so creating a second one returns 422.

calculation_mode sets the unit of every number in the budget: fee counts money in the project's currency, time counts hours. amount is a plain decimal in that unit, not cents — "5000" on a fee budget is 5,000.00 and "37.5" on a time budget is 37.5 hours.

calculation_base has to be one the mode can count, and any other is rejected:

calculation_mode calculation_base
fee billable_time, billable_time_and_expenses, expenses
time billable_time, non_billable_time, billable_and_non_billable_time

Every setting you leave out is taken from the company's budget settings in Bonsai, the ones the app pre-fills. A default calculation_base the mode cannot count becomes billable_time.

The project needs a start_date, because budget cycles run from it; set one with PATCH /public-api/v1/projects/{id} first. A project that starts in the future gets its budget right away, and its first cycle opens on the start date.

A project the token cannot see returns 404. One it can see returns 403 when the token may not change the project or see its budget, or when the plan does not include budgets.

Path Parameters

  • project_id
    Type: integer
    required

    The project's id.

Body

required
application/json

The budget, wrapped in a budget key.

  • budget
    Type: object
    required
    Properties: 7

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/public-api/v1/projects/{project_id}/budget
curl https://app.hellobonsai.com/public-api/v1/projects/1/budget \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "budget": {
    "calculation_mode": "fee",
    "amount": "5000",
    "calculation_base": "billable_time_and_expenses",
    "expenses_calculation_base": "billable",
    "reset_frequency": "monthly",
    "over_budget_notification": "enabled",
    "over_budget_notification_threshold": "80"
  }
}'

{
  "data": {
    "id": 41,
    "amount": "5000.0",
    "over_budget_notification_threshold": "80.0",
    "calculation_mode": "fee",
    "calculation_base": "billable_time_and_expenses",
    "expenses_calculation_base": "all",
    "reset_frequency": "monthly",
    "over_budget_notification": "enabled",
    "current_cycle": {
      "opening_date": "2026-03-01",
      "closing_date": "2026-03-31",
      "consumed_amount": "1250.0",
      "consumed_percentage": 25
    }
  },
  "meta": {
    "request_id": "b1f0d2c4-7a9e-4c3b-8d5f-1e2a3b4c5d6e"
  }
}

The budget was created.