Create a new budget

POST

/budgets

curl --request POST \
  --url http://localhost:8000/api/v1/budgets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "client_id": "example", "name": "example", "description": "example", "amount": 1, "currency": "USD", "period_type": "weekly", "start_date": "2026-04-15", "end_date": "2026-04-15", "rollover_enabled": true, "threshold_percent": 1, "forecast_alerts_enabled": true, "is_active": true, "targets": [ { "type": "category", "id": 1 } ], "owner": { "type": "user", "id": 1 }, "created_at": "2026-04-15T12:00:00Z" }'

• Local server
• Development server
• Dynamic server URL

Authorizations

• bearerAuth

Request Body ^required

Media type application/json

object

client_id

string

nullable

name

required

string

<= 255 characters

description

string

nullable

amount

required

number format: float

currency

required

string

Example

USD

period_type

required

string

Allowed values: weekly monthly yearly custom

start_date

required

string format: date

end_date

string format: date

nullable

rollover_enabled

boolean

threshold_percent

integer

<= 100

forecast_alerts_enabled

boolean

is_active

boolean

targets

Array<object>

object

type

string

Allowed values: category group wallet

id

integer

owner

object

type

string

Allowed values: user

id

integer

created_at

string format: date-time

nullable

Responses

201

Budget created

Media type application/json

object

id

integer

owner_id

integer

owner_type

string

name

string

slug

string

description

string

nullable

amount

number format: float

currency

string

period_type

string

Allowed values: weekly monthly yearly custom

start_date

string format: date

end_date

string format: date

nullable

rollover_enabled

boolean

threshold_percent

integer

forecast_alerts_enabled

boolean

is_active

boolean

targets

Array<object>

object

type

string

Allowed values: category group wallet

id

integer

client_generated_id

string

nullable

name

string

progress

object

period_start

string format: date

period_end

string format: date

limit

number format: float

gross_spent

number format: float

refunds

number format: float

net_spent

number format: float

rollover_in

number format: float

effective_limit

number format: float

remaining

number format: float

percent_used

integer

projected_spend

number format: float

status

string

Allowed values: on_track near_limit over_budget forecast_breach

client_generated_id

string

nullable

last_synced_at

string format: date-time

nullable

created_at

string format: date-time

updated_at

string format: date-time

deleted_at

string format: date-time

nullable

Example

{
  "owner_type": "App\\Models\\User",
  "currency": "USD",
  "period_type": "weekly",
  "threshold_percent": 80,
  "targets": [
    {
      "type": "category"
    }
  ],
  "progress": {
    "status": "on_track"
  }
}

403

Forbidden owner

422

Validation error