Skip to content

Create a budget

Request

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

Security
BearerAuth
Path
client_idintegerrequired

The ID of the business.

Example:123
Bodyapplication/jsonrequired
namestring, <= 128 charactersrequired

The name of the budget.

Example:"Sales Team"
reset_amountnumberrequired

The amount the budget resets to each period.

Example:1000
reset_periodstring(BudgetResetPeriod)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"
Example:"MONTHLY"
has_member_limitsbooleanrequired

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.

Example:false
rollover_fundsbooleanrequired

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

Example:false
membersArray of objects, non-empty(BudgetMemberInput)required
ownersArray of objects, non-empty(BudgetOwnerInput)required
limit_categoriesboolean

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

Default:false
Example:false
categoriesArray of strings, (uuid)

Category ids that should be visible on the budget.

custom_fieldsArray of objects(BudgetCustomFieldInput)
curl -i -X POST \
  https://public.letsweel.com/v1/businesses/123/budgets \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Sales Team",
    "reset_amount": 1000,
    "reset_period": "MONTHLY",
    "has_member_limits": false,
    "rollover_funds": false,
    "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"
        }
      }
    ],
    "limit_categories": false,
    "categories": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
    "custom_fields": [
      {
        "id": "a2b1d8c0-9a4e-4b8a-bf24-90af44a98e2f",
        "allow_options": [
          "497f6eca-6276-4993-bfeb-53cbbbba6f08"
        ]
      }
    ]
  }'

Responses

Created

Bodyapplication/json
idstringrequired

The ID of the budget.

Example:"e33b7c61-5124-4ba0-b238-e4c573133715"
namestringrequired

The name of the budget.

Example:"Sales Team"
budget_typestringrequired

The type of budget.

Enum:"BUDGET""SUBSCRIPTION"
Example:"BUDGET"
available_amountnumberrequired

The available amount of the budget.

Example:800
spent_amountnumberrequired

The amount of the budget that has been spent.

Example:200
reset_amountnumberrequired

The reset amount of the budget.

Example:1000
reset_periodstring(BudgetResetPeriod)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"
Example:"MONTHLY"
current_period_startstring or null, (date-time)required

The start date of the current period in UTC.

Example:"2024-01-01T00:00:00Z"
current_period_endstring or null, (date-time)required

The end date of the current period in UTC.

Example:"2024-01-31T23:59:59Z"
has_member_limitsbooleanrequired

Whether the budget has member limits.

Example:false
rollover_fundsbooleanrequired

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

Example:false
limit_categoriesbooleanrequired

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

Example:false
categoriesArray of objectsrequired

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

custom_fieldsArray of objectsrequired

Custom fields attached to this budget.

is_deletedbooleanrequired

Whether the budget is deleted.

Example:false
createdstring, (date-time)required

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

Example:"2024-01-01T00:00:00Z"
updatedstring, (date-time)required

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

Example:"2024-01-01T00:00:00Z"
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",
  "has_member_limits": false,
  "rollover_funds": false,
  "limit_categories": false,
  "categories": [
    { … }
  ],
  "custom_fields": [
    { … }
  ],
  "is_deleted": false,
  "created": "2024-01-01T00:00:00Z",
  "updated": "2024-01-01T00:00:00Z"
}