v1

latestOpenAPI 3.1.02026-08-065163115.0 KB

Budgets

Create a budget

Creates a budget with the given configuration, initial members, and owners. All top-level configuration fields are required — no silent defaults.

post/v1/businesses/{client_id}/budgets

Path parameters

client_idinteger required

Example:123

The ID of the business.

Request body

namestring required

The name of the budget.

reset_amountnumber required

The amount the budget resets to each period.

The reset cadence for the budget. JULY_FINANCIAL_YEAR resets on 1 July; APRIL_FINANCIAL_YEAR resets on 1 April.

has_member_limitsboolean required

When true, each member has its own reset_amount cap and the sum of member caps must equal the budget reset_amount. When false, members share the budget's pot.

rollover_fundsboolean required

When true, unspent balance rolls over to the next period.

limit_categoriesboolean

When true, only the categories listed in categories are visible on the budget. When false, all business categories are visible.

categoriesstring[]

Category ids that should be visible on the budget.

Example request

{
  "name": "Sales Team",
  "reset_amount": 1000,
  "reset_period": "MONTHLY",
  "members": [
    {
      "user": {
        "id": 12345
      },
      "invite": {
        "id": "f4c1e25a-2a78-4f4f-9d3e-1c3a96cf21b1"
      },
      "reset_amount": 250
    }
  ],
  "owners": [
    {
      "user": {
        "id": 12345
      },
      "invite": {
        "id": "f4c1e25a-2a78-4f4f-9d3e-1c3a96cf21b1"
      }
    }
  ],
  "custom_fields": [
    {
      "id": "a2b1d8c0-9a4e-4b8a-bf24-90af44a98e2f"
    }
  ]
}

Response

Created

idstring required

The ID of the budget.

namestring required

The name of the budget.

budget_type'BUDGET' | 'SUBSCRIPTION' required

The type of budget.

available_amountnumber required

The available amount of the budget.

spent_amountnumber required

The amount of the budget that has been spent.

reset_amountnumber required

The reset amount of the budget.

The reset cadence for the budget. JULY_FINANCIAL_YEAR resets on 1 July; APRIL_FINANCIAL_YEAR resets on 1 April.

current_period_startstring date-time nullable required

The start date of the current period in UTC.

current_period_endstring date-time nullable required

The end date of the current period in UTC.

has_member_limitsboolean required

Whether the budget has member limits.

rollover_fundsboolean required

When true, unspent balance rolls over to the next period instead of resetting.

limit_categoriesboolean required

When true, only categories listed in categories are visible on the budget. When false, all enabled business categories are visible.

is_deletedboolean required

Whether the budget is deleted.

createdstring date-time required

The date and time when the budget was created in UTC.

updatedstring date-time required

The date and time when the budget was last updated in UTC.

Example response

{
  "id": "e33b7c61-5124-4ba0-b238-e4c573133715",
  "name": "Sales Team",
  "budget_type": "BUDGET",
  "available_amount": 800,
  "spent_amount": 200,
  "reset_amount": 1000,
  "reset_period": "MONTHLY",
  "current_period_start": "2024-01-01T00:00:00Z",
  "current_period_end": "2024-01-31T23:59:59Z",
  "categories": [
    {
      "id": "7f183748-c7fb-428a-9b2a-603a03dcabdb",
      "name": "Travel"
    }
  ],
  "custom_fields": [
    {
      "id": "44b2add5-eeb2-456c-8918-9bb362b0e896",
      "name": "Department"
    }
  ],
  "created": "2024-01-01T00:00:00Z",
  "updated": "2024-01-01T00:00:00Z"
}