Toshl Developer

Create budget

Create a new budget. Some related data is updated asynchronously.

POST /budgets

Required scope:

Parameters

name *
required
string

Budget name.

Max length: 255
limit *
required
number

Budget limit. If type != regular this field is read only.

Minimum: > -1000000000000000
Maximum: < 1000000000000000
currency *
required
object

Currency object
code *
required
string

Budget currency code.

Regex: [A-Z0-9_]{2,10}
rate
optional
number

Budget exchange rate calculated according to users currency. If not set (and currency differs from main currency) the daily exchange rate will be used.

Minimum: > 0
main_rate
optional
number

Entry exchange rate main currency calculated according to entry main currency.
fixed
optional
boolean

If set to true, the exchange rate is not refreshed on next budget iteration.

Default value: false
rollover
optional
boolean

Boolean which determines if rollover is enabled for budget. If rollover is enabled whatever is left of the budget limit is carried over to the next month.
rollover_override
optional
boolean

Is true if rollover is overriden with a custom amount (can be useful for smart clients).
rollover_amount
optional
number

Budget rollover amount. If client updates this the rollovers from previous months are not transferred anymore.

Minimum: > -1000000000000000
Maximum: < 1000000000000000
Default value: 0
recurrence
optional
object

Recurrence object.
frequency
optional
string

Budget frequency.

Possible values: one-time, daily, weekly, monthly, yearly
interval
optional
integer

Budget interval.

Minimum: >= 1
Maximum: =< 127
start
optional
string

Budget start date in YYYY-MM-DD format.

Format: date
end
optional
string

Budget end date in YYYY-MM-DD format.

Format: date
byday
optional
string

A weekday (MO,TU..). Each weekday can have be preceded by a positive or negative number (1MO - 1st monday of the month/year, -1MO - last monday of the month/year). Only one weekday can be set - a limitation due to the nature of budgets.
bymonthday
optional
string

A comma separated list of month days (1-31). Each month day can have a plus(+) or minus(-) prefix. Only one month day can be specified due to the nature of budgets.
bysetpos
optional
string

A comma separater list of the nth occurance within bymonthday. If you wish to set the budget to repeat on the last day of the month, set frequency to monthly, bymonthday to 28,29,30,31 and bysetpos to -1.
type *
required
string

Budget type.

Possible values: regular, delta, percent
percent
optional
number

Percent of monthly income. If type is percent this field must be set or server will report an error.

Minimum: > 0
delta
optional
number

Used to define monthly budget -/+ delta. If type if delta this field must be set or server will report an error.
tags
optional
array

An array of tag ids included in budget.
!tags
optional
array

An array of tag ids excluded from the budget.
categories
optional
array

An array of category ids included in budget.
!categories
optional
array

An array of category ids excluded from the budget.
accounts
optional
array

An array of account ids included in budget.
!accounts
optional
array

An array of account ids excluded from the budget.
extra
optional
object

A custom JSON object that you can use to extend Toshl API. Whatever you save into this field you will get back whenever you fetch it later.

* denotes required field/parameter.

Request

$ curl https://api.toshl.com/budgets \
  -H "Authorization: Bearer T9cE5asGnuyYCCqIZFoWjFHvNbvVqHjl" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{json}'

Response

HTTP/1.1 201 Created
Location: https://api.toshl.com/budgets/42