Toshl Developer

Budgets

Budgets endpoint can be used to interact with users budgets. Endpoint returns only active budgets (can also return deleted budgets if include_deleted is true). If a client does not know how to calculate a budgets history it can set expand to true and the API will do the work. For this to work well, please include from and to whenever possible.

Note: Only one active monthly budget for all expenses can exist at any one time. If a user tries to add a second general monthly budget, a 403 (Forbidden) error will be returned and the budget will be discarded.

Note: Be advised that budgets are subject to free account limitation. If a user with a free account tries to add a third budget, a 403 (Forbidden) error will be returned and the budget will be discarded.

Resource representation

{
  "id": "42",
  "name": "Monthly budget",
  "limit": 1000,
  "amount": 78.4,
  "planned": 12.6,
  "median": 22,
  "currency": {
    "code": "USD",
    "rate": 1,
    "fixed": false
  },
  "from": "2013-02-01",
  "to": "2013-02-30",
  "rollover": false,
  "modified": "2013-06-27T14:14:03+00:00Z",
  "recurrence": {
    "frequency": "monthly",
    "interval": 1,
    "start": "2012-06-01",
    "iteration": 4
  },
  "status": "active",
  "type": "regular",
  "order": 0,
  "categories": ["42"]
}

Properties

id
readonly
string

Budget id.

parent
readonly
string

Budget parent id.

name
read, write
string

Budget name.

Max length: 300
limit
read, write
number

Budget limit.

Minimum: > -1000000000000000
Maximum: < 1000000000000000
limit_planned
readonly
number

Planned budget limit is the limit based only on planned incomes.

Minimum: > -1000000000000000
Maximum: < 1000000000000000
amount
readonly
number

Budget amount, always calculated into budget currency.

Minimum: >= 0
Maximum: < 1000000000000000
planned
readonly
number

Planned amount is the amount of expenses that will fall into the budget after today.

Minimum: >= 0
Maximum: < 1000000000000000
history_amount_median
readonly
number

Budget history amount median.

Minimum: >= 0
Maximum: < 1000000000000000
currency
read, write
object

Currency object

code
read, write
string

Budget currency code. Currency code is updatable only if all iterations are updated, or if budget is non repeating

Regex: [A-Z0-9_]{2,10}
rate
read, write
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
readonly
number

Entry exchange rate main currency calculated according to entry main currency.

fixed
read, write
boolean

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

Default value: false
from
readonly
string

Budget start date.

Format: date
to
readonly
string

Budget end date.

Format: date
rollover
read, write
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
read, write
boolean

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

rollover_amount
read, write
number

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

Minimum: > -1000000000000000
Maximum: < 1000000000000000
Default value: 0
rollover_amount_planned
readonly
number

Planned budget rollover amount. It takes into account aonly planned expenses.

Minimum: > -1000000000000000
Maximum: < 1000000000000000
Default value: 0
modified
readonly
string

Specifies when the budget was last modified.

recurrence
read, write
object

Recurrence object.

frequency
read, write
string

Budget frequency.

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

Budget interval.

Minimum: >= 1
Maximum: =< 127
start
read, write
string

Budget start date in YYYY-MM-DD format.

Format: date
end
read, write
string

Budget end date in YYYY-MM-DD format.

Format: date
byday
read, write
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
read, write
string

A comma separated list of unique month days (1-31). Each month day can have a plus(+) prefix. Only one month day can be specified due to the nature of budgets. In the case of bysetpos being -1, the value can be 28,29,30,31 or 28,29,30 or 28,29

bysetpos
read, write
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.

iteration
readonly
integer

Budget iteration number. First budget in iteration has iteration=0.

Minimum: >= 0
status
readonly
string

Budget status. Budget can have an inactive state if users pro account has expired.

Possible values: active, inactive, archived
type
read, write
string

Budget type.

Possible values: regular, delta, percent
percent
read, write
number

Percent of monthly income.

Minimum: > 0
delta
read, write
number

Used to define monthly budget -/+ delta.

order
read, write
integer

Budget order.

Minimum: >= 0
Maximum: =< 255
tags
read, write
array

An array of tag ids included in budget.

!tags
read, write
array

An array of tag ids excluded from the budget.

categories
read, write
array

An array of category ids included in budget.

!categories
read, write
array

An array of category ids excluded from the budget.

accounts
read, write
array

An array of account ids included in budget.

!accounts
read, write
array

An array of account ids excluded from the budget.

deleted
readonly
boolean

Is object deleted.

recalculated
readonly
boolean

Is true if budget balance and rollovers have been calculated (if false try pulling again until true).

extra
read, write
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.

problem
read, write
object

Budget problem info object

id
read, write
string

Id of the problem.

description
read, write
string

Description of the problem.

deleted_accounts
read, write
array

An array of ids of deleted accounts of the budget.

deleted_tags
read, write
array

An array of ids of deleted tags of the budget.

deleted_categories
read, write
array

An array of ids of deleted categories of the budget.

* denotes required field/parameter.