Skip to content

Deprecate budgets #81

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jpjpjp wants to merge 1 commit into
base: main
Choose a base branch
from
+85 −46
Open

Deprecate budgets #81

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
131 changes: 85 additions & 46 deletions source/includes/_budget.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,49 +1,65 @@
# Budget

The v1/budgets API is deprecated. Developers are encouraged to migrate their application to the new [v2/summary API](https://alpha.lunchmoney.dev/v2/docs#tag/summary) instead.

## Budget Object

Attribute Name | Type | Nullable | Description
------------------- | ------- | -------- | -----------
category_name | string | false | Name of the category, will be "Uncategorized" if no category is assigned
category_id | number | true | Unique identifier for category, can be null when `category_name` is "Uncategorized"
category_group_name | string | true | Name of the category group, if applicable
group_id | number | true | Unique identifier for category group
is_group | boolean | true | If true, this category is a group
is_income | boolean | false | If true, this category is an income category (category properties are set in the app via the Categories page)
exclude_from_budget | boolean | false | If true, this category is excluded from budget (category properties are set in the app via the Categories page)
exclude_from_totals | boolean | false | If true, this category is excluded from totals (category properties are set in the app via the Categories page)
data | Data[] | false | For each month with budget or category spending data, there is a data object with the key set to the month in format YYYY-MM-DD. For properties, see Data object below.
config | object | true | Object representing the category's budget suggestion configuration
order | number | false | Numerical ordering of budgets
archived | boolean | false | True if the category is archived and not displayed in relevant areas of the Lunch Money app.
recurring | object | true | Returns a list object that contains an array of Recurring Expenses objects (just the `payee`, `amount`, `currency`, and `to_base` fields) that affect this budget
| Attribute Name | Type | Nullable | Description |
| ------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| category_name | string | false | Name of the category, will be "Uncategorized" if no category is assigned |
| category_id | number | true | Unique identifier for category, can be null when `category_name` is "Uncategorized" |
| category_group_name | string | true | Name of the category group, if applicable |
| group_id | number | true | Unique identifier for category group |
| is_group | boolean | true | If true, this category is a group |
| is_income | boolean | false | If true, this category is an income category (category properties are set in the app via the Categories page) |
| exclude_from_budget | boolean | false | If true, this category is excluded from budget (category properties are set in the app via the Categories page) |
| exclude_from_totals | boolean | false | If true, this category is excluded from totals (category properties are set in the app via the Categories page) |
| data | Data[] | false | For each month with budget or category spending data, there is a data object with the key set to the month in format YYYY-MM-DD. For properties, see Data object below. |
| config | object | true | Object representing the category's budget suggestion configuration. Will be `null` if the category has no budget configuration set. See Config Object below for details. |
| order | number | false | Numerical ordering of budgets |
| archived | boolean | false | True if the category is archived and not displayed in relevant areas of the Lunch Money app. |
| recurring | object | true | Returns a list object that contains an array of Recurring Expenses objects (just the `payee`, `amount`, `currency`, and `to_base` fields) that affect this budget |

**Note:** A category may appear in the budget response even if no budget has been set for it. This can happen when:
- The category has transactions but no budget entries have been created
- The category has a custom budget period configured but no budget amounts have been set
- Budget entries were deleted but transactions still exist for that category
- After a users existing v1 budgets were migrated to v2 budgets, if a user changed their budget period settings (quantity, granularity, or anchor date), categories without budget values may exist.

In these cases, the `config` property will be `null`, and the `data` object will contain spending information (`spending_to_base`, `num_transactions`) but all `budget_*` properties will be `null`.

## Data Object

Attribute Name | Type | Nullable | Description
------------------- | ------- | -------- | -----------
budget_amount | number | true | The budget amount, as set by the user. If empty, no budget has been set.
budget_currency | string | true | The budget currency, as set by the user. If empty, no budget has been set.
budget_to_base | number | true | The budget converted to the user's primary currency. If the multicurrency feature is not being used, budget_to_base and budget_amount will be the same. If empty, no budget has been set.
spending_to_base | number | false | The total amount spent in this category for this time period in the user's primary currency
num_transactions | number | false | Number of transactions that make up "spending_to_base"
is_automated | boolean | true | If true, the budget_amount is only a suggestion based on the set config. If not present, it is false (meaning this is a locked in budget)
| Attribute Name | Type | Nullable | Description |
| ---------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| budget_amount | number | true | The budget amount, as set by the user. Will be `null` if no budget has been set for this category and time period. |
| budget_currency | string | true | The budget currency, as set by the user. Will be `null` if no budget has been set for this category and time period. |
| budget_to_base | number | true | The budget converted to the user's primary currency. If the multicurrency feature is not being used, budget_to_base and budget_amount will be the same. Will be `null` if no budget has been set for this category and time period. |
| spending_to_base | number | false | The total amount spent in this category for this time period in the user's primary currency. This value will always be present, even if no budget has been set. |
| num_transactions | number | false | Number of transactions that make up "spending_to_base". This value will always be present, even if no budget has been set. |
| is_automated | boolean | true | If true, the budget_amount is only a suggestion based on the set config. If not present, it is false (meaning this is a locked in budget). Will be `null` if no budget has been set. |

**Note:** When a category has transactions but no budget entries, the `data` object will still be present with spending information, but all `budget_*` properties will be `null`. This allows you to see spending activity even when budgets haven't been configured.

## Config Object

Attribute Name | Type | Nullable | Description
------------------- | ------ | -------- | -----------
config_id | number | false | Unique identifier for config
cadence | string | false | One of:<br> <ul> <li>monthly</li> <li>twice a month</li> <li>once a week</li> <li>every 3 months</li> <li>every 4 months</li> <li>twice a year</li> <li>yearly</li></ul>
amount | number | false | Amount in numeric format
currency | string | false | Three-letter lowercase currency code for the recurring expense in ISO 4217 format
to_base | number | false | The amount converted to the user's primary currency.
auto_suggest | string | false | One of:<br> <ul> <li>budgeted</li> <li>fixed</li> <li>fixed-rollover</li> <li>spent</li> </ul>
| Attribute Name | Type | Nullable | Description |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| config_id | number | false | Unique identifier for config |
| cadence | string | false | One of:<br> <ul> <li>monthly</li> <li>twice a month</li> <li>once a week</li> <li>every 3 months</li> <li>every 4 months</li> <li>twice a year</li> <li>yearly</li></ul> |
| amount | number | false | Amount in numeric format |
| currency | string | false | Three-letter lowercase currency code for the recurring expense in ISO 4217 format |
| to_base | number | false | The amount converted to the user's primary currency. |
| auto_suggest | string | false | One of:<br> <ul> <li>budgeted</li> <li>fixed</li> <li>fixed-rollover</li> <li>spent</li> </ul> |

**Note:** The `config` property in the Budget Object can be `null`. When `config` is `null`, it means the category has no budget configuration set. When `config` is present (not null), all properties listed above are required and not nullable.

## Get Budget Summary

Use this endpoint to get full details on the budgets for all budgetable categories between a certain time period. The budgeted and spending amounts will be broken down by month.

**Note:** Categories may appear in the response even if they have no budget entries, as long as they have transactions in the specified time period. In these cases, `config` will be `null` and all `budget_*` properties in the `data` object will be `null`, but `spending_to_base` and `num_transactions` will still be populated.

> Example 200 Response

```json
Expand Down Expand Up @@ -129,6 +145,29 @@ Use this endpoint to get full details on the budgets for all budgetable categori
}
]
}
},
{
"category_name": "Unbudgeted Category",
"category_id": 12345,
"category_group_name": null,
"group_id": null,
"is_group": false,
"is_income": false,
"exclude_from_budget": false,
"exclude_from_totals": false,
"data": {
"2020-09-01": {
"spending_to_base": 50.00,
"num_transactions": 1,
"budget_to_base": null,
"budget_amount": null,
"budget_currency": null
}
},
"config": null,
"order": 2,
"archived": false,
"recurring": null
}
]
```
Expand All @@ -139,11 +178,11 @@ Use this endpoint to get full details on the budgets for all budgetable categori

### Query Parameters

Parameter | Type | Required | Default | Description
---------- | ------ | -------- | ------- | -----------
start_date | string | true | - | Start date for the budget period. Lunch Money currently only supports monthly budgets, so your date should be the start of a month (eg. 2021-04-01)
end_date | string | true | - | End date for the budget period. Lunch Money currently only supports monthly budgets, so your date should be the end of a month (eg. 2021-04-30)
currency | string | false | - | Currency for the budgeted amount (optional). If empty, will default to your primary currency
| Parameter | Type | Required | Default | Description |
| ---------- | ------ | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| start_date | string | true | - | Start date for the budget period. Lunch Money currently only supports monthly budgets, so your date should be the start of a month (eg. 2021-04-01) |
| end_date | string | true | - | End date for the budget period. Lunch Money currently only supports monthly budgets, so your date should be the end of a month (eg. 2021-04-30) |
| currency | string | false | - | Currency for the budgeted amount (optional). If empty, will default to your primary currency |

## Upsert Budget

Expand Down Expand Up @@ -178,12 +217,12 @@ If this is a sub-category, the response will include the updated category group'

### Body Parameters

Parameter | Type | Required | Default | Description
----------- | ------ | -------- | ------- | -----------
start_date | string | true | - | Start date for the budget period. Lunch Money currently only supports monthly budgets, so your date must always be the start of a month (eg. 2021-04-01)
category_id | number | true | - | Unique identifier for the category
amount | number | true | - | Amount for budget
currency | string | false | - | Currency for the budgeted amount (optional). If empty, will default to your primary currency
| Parameter | Type | Required | Default | Description |
| ----------- | ------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| start_date | string | true | - | Start date for the budget period. Lunch Money currently only supports monthly budgets, so your date must always be the start of a month (eg. 2021-04-01) |
| category_id | number | true | - | Unique identifier for the category |
| amount | number | true | - | Amount for budget |
| currency | string | false | - | Currency for the budgeted amount (optional). If empty, will default to your primary currency |

## Remove Budget

Expand All @@ -207,9 +246,9 @@ true

### Query Parameters

Parameter | Type | Required | Default | Description
----------- | ------ | -------- | ------- | -----------
start_date | string | true | - | Start date for the budget period. Lunch Money currently only supports monthly budgets, so your date must always be the start of a month (eg. 2021-04-01)
category_id | number | true | - | Unique identifier for the category
| Parameter | Type | Required | Default | Description |
| ----------- | ------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| start_date | string | true | - | Start date for the budget period. Lunch Money currently only supports monthly budgets, so your date must always be the start of a month (eg. 2021-04-01) |
| category_id | number | true | - | Unique identifier for the category |

---