---
title: "Create a budget"
method: POST
path: "/v1/businesses/{client_id}/budgets"
tags: ["Budgets"]
---

# Create a budget

`POST /v1/businesses/{client_id}/budgets`

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

## Path parameters

- `client_id` integer, required

## Request body

- BudgetCreateRequest
  - `name` string, required — The name of the budget.
  - `reset_amount` number, required — The amount the budget resets to each period.
  - `reset_period` 'DAILY' | 'WEEKLY' | 'FORTNIGHTLY' | 'MONTHLY' | 'QUARTERLY' | 'ANNUALLY' | 'JULY_FINANCIAL_YEAR' | 'APRIL_FINANCIAL_YEAR' | 'NEVER', required — The reset cadence for the budget. JULY_FINANCIAL_YEAR resets on 1 July; APRIL_FINANCIAL_YEAR resets on 1 April.
  - `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` BudgetMemberInput[], required
    - union — A member to attach to the budget. Provide exactly one of `user` or `invite`. `reset_amount` is required when `has_member_limits` is true and must be omitted otherwise; the sum of member `reset_amount` values must equal the budget's `reset_amount`.
      - object
        - `user` BudgetUserRef, required — Reference to an existing Weel user by id.
          - `id` integer, required — The id of the user.
        - `invite` BudgetInviteRef — Reference to an outstanding invite by id.
          - `id` string, uuid, required — The id of the invite.
        - `reset_amount` number — The per-member spending cap when has_member_limits is true.
      - object
        - `user` BudgetUserRef — Reference to an existing Weel user by id.
          - `id` integer, required — The id of the user.
        - `invite` BudgetInviteRef, required — Reference to an outstanding invite by id.
          - `id` string, uuid, required — The id of the invite.
        - `reset_amount` number — The per-member spending cap when has_member_limits is true.
  - `owners` BudgetOwnerInput[], required
    - union — An owner (budget approver) to attach to the budget. Provide exactly one of `user` or `invite`.
      - object
        - `user` BudgetUserRef, required — Reference to an existing Weel user by id.
          - `id` integer, required — The id of the user.
        - `invite` BudgetInviteRef — Reference to an outstanding invite by id.
          - `id` string, uuid, required — The id of the invite.
      - object
        - `user` BudgetUserRef — Reference to an existing Weel user by id.
          - `id` integer, required — The id of the user.
        - `invite` BudgetInviteRef, required — Reference to an outstanding invite by id.
          - `id` string, uuid, required — The id of the invite.
  - `limit_categories` boolean — When true, only the categories listed in `categories` are visible on the budget. When false, all business categories are visible.
  - `categories` string[] — Category ids that should be visible on the budget.
  - `custom_fields` BudgetCustomFieldInput[]
    - `id` string, uuid, required — The id of the custom field.
    - `allow_options` string[] — List item ids that should remain selectable on this budget.

## Response `201`

Created

- Budget
  - `id` string, required — The ID of the budget.
  - `name` string, required — The name of the budget.
  - `budget_type` 'BUDGET' | 'SUBSCRIPTION', required — The type of budget.
  - `available_amount` number, required — The available amount of the budget.
  - `spent_amount` number, required — The amount of the budget that has been spent.
  - `reset_amount` number, required — The reset amount of the budget.
  - `reset_period` 'DAILY' | 'WEEKLY' | 'FORTNIGHTLY' | 'MONTHLY' | 'QUARTERLY' | 'ANNUALLY' | 'JULY_FINANCIAL_YEAR' | 'APRIL_FINANCIAL_YEAR' | 'NEVER', required — The reset cadence for the budget. JULY_FINANCIAL_YEAR resets on 1 July; APRIL_FINANCIAL_YEAR resets on 1 April.
  - `current_period_start` string, date-time, nullable, required — The start date of the current period in UTC.
  - `current_period_end` string, date-time, nullable, required — The end date of the current period in UTC.
  - `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` object[], required — Categories currently visible on the budget. Returns an empty array when `limit_categories` is false (no restriction in force).
    - `id` string, uuid, required
    - `name` string, required
  - `custom_fields` object[], required — Custom fields attached to this budget.
    - `id` string, uuid, required — The id of the custom field.
    - `name` string, required
    - `allow_options` string[], nullable, 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, date-time, required — The date and time when the budget was created in UTC.
  - `updated` string, date-time, required — The date and time when the budget was last updated in UTC.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `429` — Too Many Requests

---

[API](https://skmtc.net/letsweel/apis/weel-openapi.md) · [All operations](https://skmtc.net/letsweel/apis/weel-openapi/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/letsweel/weel-openapi/revisions/55da5fa350fb/schema)