Summary

Summary endpoint can be used to retrieve an overview of users expenses, incomes and budgets for the desired from - to timespan.

Resource representation

{
  "from": "2014-01-01",
  "to": "2014-01-31",
  "expenses": {
    "sum": 1540,
    "count": 23,
    "daily_median": 50.4
  },
  "incomes": {
    "sum": 2300,
    "count": 1,
    "daily_median": 2000
  },
  "budget": {
    "id": "42",
    "amount": 1540,
    "limit": 1800
  },
  "left": 260
}

Properties

from readonly `string`	Timespan start date in `YYYY-MM-DD` format. Format: `date`
to readonly `string`	Timespan end date in `YYYY-MM-DD` format. Format: `date`
expenses readonly `object`	Expenses overview of the given timespan.
sum readonly `number`	Expense sum for timespan. Minimum: `> -1000000000000000` Maximum: `< 1000000000000000`
sum_planned readonly `number`	Planned expense sum for timespan. Minimum: `> -1000000000000000` Maximum: `< 1000000000000000`
count readonly `integer`	Expense count for timespan. Minimum: `>= 0`
daily_median readonly `number`	Median of daily expense sums. Zero sums are ignored. Minimum: `>= 0`
all_time_avg readonly `number`	All time average for selected accounts Minimum: `> -1000000000000000` Maximum: `< 1000000000000000`
incomes readonly `object`	Income overview of the given timespan.
sum readonly `number`	Income sum for timespan. Minimum: `> -1000000000000000` Maximum: `< 1000000000000000`
sum_planned readonly `number`	Planned income sum for timespan. Minimum: `> -1000000000000000` Maximum: `< 1000000000000000`
count readonly `integer`	Income count for timespan. Minimum: `>= 0`
daily_median readonly `number`	Median of daily income sums. Zero sums are ignored. Minimum: `>= 0`
all_time_avg readonly `number`	All time average for selected accounts Minimum: `> -1000000000000000` Maximum: `< 1000000000000000`
budget read, write `object`	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.\n_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.\n_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.
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.
left readonly `number`	Amount left to spend for selected timestamp. If the amount is negative the user went over the income/budget limit. Minimum: `> -1000000000000000` Maximum: `< 1000000000000000`
left_planned readonly `number`	Amount left to spend based on planned entriesfor selected timestamp. If the amount is negative the user went over the income/budget limit. Minimum: `> -1000000000000000` Maximum: `< 1000000000000000`
balance readonly `number`	Balance until today Minimum: `> -1000000000000000` Maximum: `< 1000000000000000`

* denotes required field/parameter.

Page last modified: 08 Jan 2024