# Create a budget

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

Endpoint: POST /v1/businesses/{client_id}/budgets
Version: v1
Security: BearerAuth

## Path parameters:

  - `client_id` (integer, required)
    The ID of the business.
    Example: 123

## Request fields (application/json):

  - `name` (string, required)
    The name of the budget.
    Example: "Sales Team"

  - `reset_amount` (number, required)
    The amount the budget resets to each period.
    Example: 1000

  - `reset_period` (string, required)
    The reset cadence for the budget. JULY_FINANCIAL_YEAR resets on 1 July;
APRIL_FINANCIAL_YEAR resets on 1 April.
    Enum: "DAILY", "WEEKLY", "FORTNIGHTLY", "MONTHLY", "QUARTERLY", "ANNUALLY", "JULY_FINANCIAL_YEAR", "APRIL_FINANCIAL_YEAR", "NEVER"

  - `has_member_limits` (boolean, 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_funds` (boolean, required)
    When true, unspent balance rolls over to the next period.

  - `members` (array, required)

  - `members.user` (object)
    Reference to an existing Weel user by id.

  - `members.user.id` (integer, required)
    The id of the user.
    Example: 12345

  - `members.invite` (object)
    Reference to an outstanding invite by id.

  - `members.invite.id` (string, required)
    The id of the invite.
    Example: "f4c1e25a-2a78-4f4f-9d3e-1c3a96cf21b1"

  - `members.reset_amount` (number)
    The per-member spending cap when has_member_limits is true.
    Example: 250

  - `owners` (array, required)

  - `owners.user` (object)
    Reference to an existing Weel user by id.

  - `owners.invite` (object)
    Reference to an outstanding invite by id.

  - `limit_categories` (boolean)
    When true, only the categories listed in categories are visible
on the budget. When false, all business categories are visible.

  - `categories` (array)
    Category ids that should be visible on the budget.

  - `custom_fields` (array)

  - `custom_fields.id` (string, required)
    The id of the custom field.
    Example: "a2b1d8c0-9a4e-4b8a-bf24-90af44a98e2f"

  - `custom_fields.allow_options` (array)
    List item ids that should remain selectable on this budget.

## Response 201 fields (application/json):

  - `id` (string, required)
    The ID of the budget.
    Example: "e33b7c61-5124-4ba0-b238-e4c573133715"

  - `name` (string, required)
    The name of the budget.
    Example: "Sales Team"

  - `budget_type` (string, required)
    The type of budget.
    Enum: "BUDGET", "SUBSCRIPTION"

  - `available_amount` (number, required)
    The available amount of the budget.
    Example: 800

  - `spent_amount` (number, required)
    The amount of the budget that has been spent.
    Example: 200

  - `reset_amount` (number, required)
    The reset amount of the budget.
    Example: 1000

  - `reset_period` (string, required)
    The reset cadence for the budget. JULY_FINANCIAL_YEAR resets on 1 July;
APRIL_FINANCIAL_YEAR resets on 1 April.
    Enum: same as `reset_period` (9 values)

  - `current_period_start` (string,null, required)
    The start date of the current period in UTC.
    Example: "2024-01-01T00:00:00Z"

  - `current_period_end` (string,null, required)
    The end date of the current period in UTC.
    Example: "2024-01-31T23:59:59Z"

  - `has_member_limits` (boolean, required)
    Whether the budget has member limits.

  - `rollover_funds` (boolean, required)
    When true, unspent balance rolls over to the next period instead of resetting.

  - `limit_categories` (boolean, required)
    When true, only categories listed in categories are visible on
the budget. When false, all enabled business categories are visible.

  - `categories` (array, required)
    Categories currently visible on the budget. Returns an empty array
when limit_categories is false (no restriction in force).

  - `categories.id` (string, required)
    Example: "7f183748-c7fb-428a-9b2a-603a03dcabdb"

  - `categories.name` (string, required)
    Example: "Travel"

  - `custom_fields` (array, required)
    Custom fields attached to this budget.

  - `custom_fields.id` (string, required)
    The id of the custom field.
    Example: "44b2add5-eeb2-456c-8918-9bb362b0e896"

  - `custom_fields.name` (string, required)
    Example: "Department"

  - `custom_fields.allow_options` (array,null, required)
    For LIST-type custom fields, the list-item ids selectable on
this budget. null means no per-budget restriction (all
enabled options are selectable). An empty array means no
options are selectable on this budget. Always null for
FREE_TEXT custom fields.

  - `is_deleted` (boolean, required)
    Whether the budget is deleted.

  - `created` (string, required)
    The date and time when the budget was created in UTC.
    Example: "2024-01-01T00:00:00Z"

  - `updated` (string, required)
    The date and time when the budget was last updated in UTC.
    Example: "2024-01-01T00:00:00Z"


## Response 400 fields

## Response 401 fields

## Response 403 fields

## Response 429 fields