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.

Page last modified: 08 Jan 2024