LunchMoney

The LunchMoney client is the main entrypoint for interacting with the Lunch Money API. It defaults to inheriting the LUNCHMONEY_ACCESS_TOKEN environment variable, but can be created with an explicit access_token parameter.

from lunchable import LunchMoney

lunch = LunchMoney(access_token="xxxxxxxxxxx")

Methods

HTTP Verb	Name	Description
GET	get_assets	Get Manually Managed Assets
GET	get_budgets	Get Monthly Budgets
GET	get_categories	Get Spending categories
GET	get_category	Get single category
GET	get_crypto	Get Crypto Assets
GET	get_plaid_accounts	Get Plaid Synced Assets
GET	get_recurring_expenses	Get Recurring Expenses
GET	get_tags	Get Spending Tags
GET	get_transaction	Get a Transaction by ID
GET	get_transactions	Get Transactions Using Criteria
GET	get_user	Get Personal User Details
POST	insert_asset	Create a single (manually-managed) asset
POST	insert_category	Create a Spending Category
POST	insert_category_group	Create a Spending Category Group
POST	insert_into_category_group	Add to a Category Group
POST	insert_transaction_group	Create a Transaction Group of Two or More Transactions
POST	insert_transactions	Create One or Many Lunch Money Transactions
POST	trigger_fetch_from_plaid	Trigger a Plaid Sync
POST	unsplit_transactions	Unsplit Transactions
PUT	upsert_budget	Upsert a Budget for a Category and Date
PUT	update_asset	Update a Single Asset
PUT	update_category	Update a single category
PUT	update_crypto	Update a Manual Crypto Asset
PUT	update_transaction	Update a Transaction
DELETE	remove_budget	Unset an Existing Budget for a Particular Category in a Particular Month
DELETE	remove_category	Delete a single category
DELETE	remove_category_force	Forcefully delete a single category
DELETE	remove_transaction_group	Delete a Transaction Group

Low Level Methods

Name	Description
request	Make an HTTP request
arequest	Make an async HTTP request
process_response	Process a Lunch Money response and raise any errors
make_request	Make an HTTP request and process its response
amake_request	Make an async HTTP request and process its response

Attributes

Name	Description
async_session	Authenticated Async HTTPX Client
session	Authenticated HTTPX Client

Class Documentation

Lunch Money Python Client.

This class facilitates with connections to the Lunch Money Developer API. Authenticate with an Access Token. If an access token isn't provided one will attempt to be inherited from a LUNCHMONEY_ACCESS_TOKEN environment variable.

Examples:

from typing import List

from lunchable import LunchMoney
from lunchable.models import TransactionObject

lunch = LunchMoney(access_token="xxxxxxx")
transactions: List[TransactionObject] = lunch.get_transactions()

async_session: httpx.AsyncClient cached property

Lunch Money HTTPX Async Client

Returns:

Type	Description
AsyncClient

session: httpx.Client cached property

Lunch Money HTTPX Client

Returns:

Type	Description
Client

Methods

HTTP Request Method Enumerations: GET, OPTIONS, HEAD, POST, PUT, PATCH, or DELETE

__init__(access_token=None)

Initialize a Lunch Money object with an Access Token.

Tries to inherit from the Environment if one isn't provided

Parameters:

Name	Type	Description	Default
access_token	Optional[str]	Lunchmoney Developer API Access Token	None

__repr__()

String Representation

Returns:

Type	Description
str

amake_request(method, url_path, params=None, payload=None, **kwargs) async

Make an async HTTP request and process its response

This method is a wrapper around :meth:.LunchMoney.arequest that also processes the response and checks for any errors.

Parameters:

Name	Type	Description	Default
method	str	requests method: GET, OPTIONS, HEAD, POST, PUT, PATCH, or DELETE	required
url_path	Union[list[Union[str, int]], str, int]	URL components to make into a URL	required
payload	Optional[Any]	Data to send in the body of the Request.	None
params	Optional[Mapping[str, Any]]	Dictionary, list of tuples or bytes to send in the query string for the Request.	None
**kwargs	Any	Additional arguments to send to the request method.	{}

Returns:

Type	Description
Any

arequest(method, url, *, content=None, data=None, json=None, params=None, **kwargs) async

Make an async HTTP request

This is a simple method :class:.LunchMoney exposes to make HTTP requests. It has the benefit of using an existing httpx.Client as well as as out of the box auth headers that are used to connect to the Lunch Money Developer API.

Parameters:

Name	Type	Description	Default
method	str	requests method: GET, OPTIONS, HEAD, POST, PUT, PATCH, or DELETE	required
url	Union[URL, str]	URL for the new Request object.	required
content	Optional[Union[str, bytes, Iterable[bytes], AsyncIterable[bytes]]]	Content to send in the body of the Request.	None
data	Optional[Mapping[str, Any]]	Dictionary, list of tuples, bytes, or file-like object to send in the body of the Request.	None
json	Optional[Any]	A JSON serializable Python object to send in the body of the Request.	None
params	Optional[Mapping[str, Any]]	Dictionary, list of tuples or bytes to send in the query string for the Request.	None
**kwargs	Any	Additional arguments to send to the request method.	{}

Returns:

Type	Description
Response

get_assets()

Get Manually Managed Assets

Get a list of all manually-managed assets associated with the user's account.

(https://lunchmoney.dev/#assets-object)

Returns:

Type	Description
List[AssetsObject]

get_budgets(start_date, end_date)

Get Monthly Budgets

Get full details on the budgets for all categories between a certain time period. The budgeted and spending amounts will be an aggregate across this time period. (https://lunchmoney.dev/#plaid-accounts-object)

Returns:

Type	Description
List[BudgetObject]

get_categories(format=None)

Get Spending categories

Use this endpoint to get a list of all categories associated with the user's account. https://lunchmoney.dev/#get-all-categories

Parameters:

Name	Type	Description	Default
format	str | CategoriesFormatEnum | None	Can either flattened or nested. If flattened, returns a singular array of categories, ordered alphabetically. If nested, returns top-level categories (either category groups or categories not part of a category group) in an array. Subcategories are nested within the category group under the property children. Defaults to None which will return a flattened list of categories.	None

Returns:

Type	Description
List[CategoriesObject]

get_category(category_id)

Get single category

Use this endpoint to get hydrated details on a single category. Note that if this category is part of a category group, its properties (is_income, exclude_from_budget, exclude_from_totals) will inherit from the category group.

https://lunchmoney.dev/#get-single-category

Parameters:

Name	Type	Description	Default
category_id	int	Id of the Lunch Money Category	required

Returns:

Type	Description
CategoriesObject

get_crypto()

Get Crypto Assets

Use this endpoint to get a list of all cryptocurrency assets associated with the user's account. Both crypto balances from synced and manual accounts will be returned.

https://lunchmoney.dev/#get-all-crypto

Returns:

Type	Description
List[CryptoObject]

get_plaid_accounts()

Get Plaid Synced Assets

Get a list of all synced Plaid accounts associated with the user's account.

Plaid Accounts are individual bank accounts that you have linked to Lunch Money via Plaid. You may link one bank but one bank might contain 4 accounts. Each of these accounts is a Plaid Account. (https://lunchmoney.dev/#plaid-accounts-object)

Returns:

Type	Description
List[PlaidAccountObject]

get_recurring_expenses(start_date=None, debit_as_negative=None)

Get Recurring Expenses

Retrieve a list of recurring expenses to expect for a specified period.

Every month, a different set of recurring expenses is expected. This is because recurring expenses can be once a year, twice a year, every 4 months, etc.

If a recurring expense is listed as “twice a month”, then that recurring expense will be returned twice, each with a different billing date based on when the system believes that recurring expense transaction is to be expected. If the recurring expense is listed as “once a week”, then that recurring expense will be returned in this list as many times as there are weeks for the specified month.

In the same vein, if a recurring expense that began last month is set to “Every 3 months”, then that recurring expense will not show up in the results for this month.

Parameters:

Name	Type	Description	Default
start_date	Optional[date]	Date to search. By default will return the first day of the current month	None
debit_as_negative	Optional[bool]	Pass in true if you'd like expenses to be returned as negative amounts and credits as positive amounts.	None

Returns:

Type	Description
List[RecurringExpensesObject]

get_tags()

Get Spending Tags

Use this endpoint to get a list of all tags associated with the user's account.

https://lunchmoney.dev/#get-all-tags

Returns:

Type	Description
List[TagsObject]

get_transaction(transaction_id, debit_as_negative=None)

Get a Transaction by ID

Parameters:

Name	Type	Description	Default
transaction_id	int	Lunch Money Transaction ID	required
debit_as_negative	Optional[bool]	Pass in true if you'd like expenses to be returned as negative amounts and credits as positive amounts. Defaults to false.	None

Returns:

Type	Description
TransactionObject

Examples:

Retrieve a single transaction by its ID

from lunchable import LunchMoney

lunch = LunchMoney(access_token="xxxxxxx")
transaction = lunch.get_transaction(transaction_id=1234)

The above code returns a TransactionObject with ID # 1234 (assuming it exists)

get_transaction_group(transaction_id)

Get a Transaction Group

Parameters:

Name	Type	Description	Default
transaction_id	int	Transaction ID of either the parent or any of the children in the transaction group	required

Returns:

Type	Description
TransactionObject	The transaction group as a TransactionObject

get_transactions(start_date=None, end_date=None, tag_id=None, recurring_id=None, plaid_account_id=None, category_id=None, asset_id=None, group_id=None, is_group=None, status=None, offset=None, limit=None, debit_as_negative=None, pending=None, params=None)

Get Transactions Using Criteria

Use this to retrieve all transactions between a date range (this method handles pagination automatically unless you specify a limit / offset argument). Returns list of Transaction objects. If no query parameters are set, this will return transactions for the current calendar month. If either start_date or end_date are datetime.datetime objects, they will be reduced to dates. If a string is provided, it will be attempted to be parsed as YYYY-MM-DD format.

Parameters:

Name	Type	Description	Default
start_date	Optional[Union[date, datetime, str]]	Denotes the beginning of the time period to fetch transactions for. Defaults to beginning of current month. Required if end_date exists. Format: YYYY-MM-DD.	None
end_date	Optional[Union[date, datetime, str]]	Denotes the end of the time period you'd like to get transactions for. Defaults to end of current month. Required if start_date exists.	None
tag_id	Optional[int]	Filter by tag. Only accepts IDs, not names.	None
recurring_id	Optional[int]	Filter by recurring expense	None
plaid_account_id	Optional[int]	Filter by Plaid account	None
category_id	Optional[int]	Filter by category. Will also match category groups.	None
asset_id	Optional[int]	Filter by asset	None
group_id	Optional[int]	Filter by group_id (if the transaction is part of a specific group)	None
is_group	Optional[bool]	Filter by group (returns transaction groups)	None
status	Optional[str]	Filter by status (Can be cleared or uncleared. For recurring transactions, use recurring)	None
offset	Optional[int]	Sets the offset for the records returned (disables automatic pagination)	None
limit	Optional[int]	Sets the maximum number of records to return. Defaults to 1000 (disables automatic pagination)	None
debit_as_negative	Optional[bool]	Pass in true if you'd like expenses to be returned as negative amounts and credits as positive amounts. Defaults to false.	None
pending	Optional[bool]	Pass in true if you'd like to include imported transactions with a pending status.	None
params	Optional[Dict[str, Any]]	Additional Query String Params	None

Returns:

Type	Description
List[TransactionObject]	A list of transactions

Examples:

Retrieve a list of TransactionObject

from lunchable import LunchMoney

lunch = LunchMoney(access_token="xxxxxxx")
transactions = lunch.get_transactions(start_date="2020-01-01",
                                      end_date="2020-01-31")

get_user()

Get Personal User Details

Use this endpoint to get details on the current user.

https://lunchmoney.dev/#get-user

Returns:

Type	Description
UserObject

insert_asset(type_name, name=None, subtype_name=None, display_name=None, balance=0.0, balance_as_of=None, currency=None, institution_name=None, closed_on=None, exclude_transactions=None)

Create a single (manually-managed) asset.

Parameters:

Name	Type	Description	Default
type_name	str	Must be one of: cash, credit, investment, other, real estate, loan, vehicle, cryptocurrency, employee compensation	required
name	Optional[str]	Max 45 characters	None
subtype_name	Optional[str]	Max 25 characters	None
display_name	Optional[str]	Display name of the asset (as set by user)	None
balance	float	Numeric value of the current balance of the account. Do not include any special characters aside from a decimal point! Defaults to 0.00	0.0
balance_as_of	Optional[datetime]	Has no effect if balance is not defined. If balance is defined, but balance_as_of is not supplied or is invalid, current timestamp will be used.	None
currency	Optional[str]	Three-letter lowercase currency in ISO 4217 format. The code sent must exist in our database. Defaults to user's primary currency.	None
institution_name	Optional[str]	Max 50 characters	None
closed_on	Optional[date]	The date this asset was closed	None
exclude_transactions	Optional[bool]	If true, this asset will not show up as an option for assignment when creating transactions manually. Defaults to False	None

Returns:

Type	Description
AssetsObject

insert_category(name, description=None, is_income=None, exclude_from_budget=None, exclude_from_totals=None, archived=None, group_id=None)

Create a Spending Category

Use this to create a single category https://lunchmoney.dev/#create-category

Parameters:

Name	Type	Description	Default
name	str	Name of category. Must be between 1 and 40 characters.	required
description	Optional[str]	Description of category. Must be less than 140 categories. Defaults to None.	None
is_income	Optional[bool]	Whether or not transactions in this category should be treated as income. Defaults to False.	None
exclude_from_budget	Optional[bool]	Whether or not transactions in this category should be excluded from budgets. Defaults to False.	None
exclude_from_totals	Optional[bool]	Whether or not transactions in this category should be excluded from calculated totals. Defaults to False.	None
archived	Optional[bool]	Whether or not category should be archived.	None
group_id	Optional[int]	Assigns the newly-created category to an existing category group.	None

Returns:

Type	Description
int	ID of the newly created category

insert_category_group(name, description=None, is_income=None, exclude_from_budget=None, exclude_from_totals=None, category_ids=None, new_categories=None)

Create a Spending Category Group

Use this endpoint to create a single category group https://lunchmoney.dev/#create-category-group

Parameters:

Name	Type	Description	Default
name	str	Name of category. Must be between 1 and 40 characters.	required
description	Optional[str]	Description of category. Must be less than 140 categories. Defaults to None.	None
is_income	Optional[bool]	Whether or not transactions in this category should be treated as income. Defaults to False.	None
exclude_from_budget	Optional[bool]	Whether or not transactions in this category should be excluded from budgets. Defaults to False.	None
exclude_from_totals	Optional[bool]	Whether or not transactions in this category should be excluded from calculated totals. Defaults to False.	None
category_ids	Optional[List[int]]	Array of category_id to include in the category group.	None
new_categories	Optional[List[str]]	Array of strings representing new categories to create and subsequently include in the category group.	None

Returns:

Type	Description
int	ID of the newly created category group

insert_into_category_group(category_group_id, category_ids=None, new_categories=None)

Add to a Category Group

Use this endpoint to add categories (either existing or new) to a single category group

https://lunchmoney.dev/#add-to-category-group

Parameters:

Name	Type	Description	Default
category_group_id	int	Id of the Lunch Money Category Group	required
category_ids	Optional[List[int]]	Array of category_id to include in the category group.	None
new_categories	Optional[List[str]]	Array of strings representing new categories to create and subsequently include in the category group.	None

Returns:

Type	Description
CategoriesObject

insert_transaction_group(date, payee, transactions, category_id=None, notes=None, tags=None)

Create a Transaction Group of Two or More Transactions

Returns the ID of the newly created transaction group

Parameters:

Name	Type	Description	Default
date	date	Date for the grouped transaction	required
payee	str	Payee name for the grouped transaction	required
category_id	Optional[int]	Category for the grouped transaction	None
notes	Optional[str]	Notes for the grouped transaction	None
tags	Optional[List[int]]	Array of tag IDs for the grouped transaction	None
transactions	List[int]	Array of transaction IDs to be part of the transaction group	required

Returns:

Type	Description
int

insert_transactions(transactions, apply_rules=None, skip_duplicates=None, debit_as_negative=None, check_for_recurring=None, skip_balance_update=None)

Create One or Many Lunch Money Transactions

Use this endpoint to insert many transactions at once. Also accepts a single transaction as well. If a TransactionObject is provided it will be converted into a TransactionInsertObject.

https://lunchmoney.dev/#insert-transactions

Parameters:

Name	Type	Description	Default
transactions	ListOrSingleTransactionInsertObject	Transactions to insert. Either a single TransactionInsertObject object or a list of them	required
apply_rules	Optional[bool]	If true, will apply account's existing rules to the inserted transactions. Defaults to false.	None
skip_duplicates	Optional[bool]	If true, the system will automatically dedupe based on transaction date, payee and amount. Note that deduping by external_id will occur regardless of this flag.	None
check_for_recurring	Optional[bool]	if true, will check new transactions for occurrences of new monthly expenses. Defaults to false.	None
debit_as_negative	Optional[bool]	If true, will assume negative amount values denote expenses and positive amount values denote credits. Defaults to false.	None
skip_balance_update	Optional[bool]	If false, will skip updating balance if an asset_id is present for any of the transactions.	None

Returns:

Type	Description
List[int]

Examples:

Create a new transaction with a TransactionInsertObject

from lunchable import LunchMoney, TransactionInsertObject

lunch = LunchMoney(access_token="xxxxxxx")

new_transaction = TransactionInsertObject(payee="Example Restaurant",
                                          amount=120.00,
                                          notes="Saturday Dinner")
new_transaction_ids = lunch.insert_transactions(transactions=new_transaction)

make_request(method, url_path, params=None, payload=None, **kwargs)

Make an HTTP request and process its response

This method is a wrapper around :meth:.LunchMoney.request that also processes the response and checks for any errors.

Parameters:

Name	Type	Description	Default
method	str	requests method: GET, OPTIONS, HEAD, POST, PUT, PATCH, or DELETE	required
url_path	Union[list[Union[str, int]], str, int]	URL components to make into a URL	required
payload	Optional[Any]	Data to send in the body of the Request.	None
params	Optional[Mapping[str, Any]]	Dictionary, list of tuples or bytes to send in the query string for the Request.	None
**kwargs	Any	Additional arguments to send to the request method.	{}

Returns:

Type	Description
Any

process_response(response) classmethod

Process a Lunch Money response and raise any errors

This includes 200 responses that are actually errors

Parameters:

Name	Type	Description	Default
response	Response	An HTTPX Response Object	required

remove_budget(start_date, category_id)

Unset an Existing Budget for a Particular Category in a Particular Month

Parameters:

Name	Type	Description	Default
start_date	date	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)	required
category_id	int	Unique identifier for the category	required

Returns:

Type	Description
bool

remove_category(category_id)

Delete a single category

Use this endpoint to delete a single category or category group. This will only work if there are no dependencies, such as existing budgets for the category, categorized transactions, categorized recurring items, etc. If there are dependents, this endpoint will return what the dependents are and how many there are.

https://lunchmoney.dev/#delete-category

Parameters:

Name	Type	Description	Default
category_id	int	Id of the Lunch Money Category	required

Returns:

Type	Description
bool

remove_category_force(category_id)

Forcefully delete a single category

Use this endpoint to force delete a single category or category group and along with it, disassociate the category from any transactions, recurring items, budgets, etc.

Note: it is best practice to first try the Delete Category endpoint to ensure you don't accidentally delete any data. Disassociation/deletion of the data arising from this endpoint is irreversible!

https://lunchmoney.dev/#force-delete-category

Parameters:

Name	Type	Description	Default
category_id	int	Id of the Lunch Money Category	required

Returns:

Type	Description
bool

remove_transaction_group(transaction_group_id)

Delete a Transaction Group

Use this method to delete a transaction group. The transactions within the group will not be removed.

Returns the IDs of the transactions that were part of the deleted group

https://lunchmoney.dev/#delete-transaction-group

Parameters:

Name	Type	Description	Default
transaction_group_id	int	Transaction Group Identifier	required

Returns:

Type	Description
List[int]

request(method, url, *, content=None, data=None, json=None, params=None, **kwargs)

Make an HTTP request

This is a simple method :class:.LunchMoney exposes to make HTTP requests. It has the benefit of using an existing httpx.Client as well as as out of the box auth headers that are used to connect to the Lunch Money Developer API.

Parameters:

Name	Type	Description	Default
method	str	requests method: GET, OPTIONS, HEAD, POST, PUT, PATCH, or DELETE	required
url	Union[URL, str]	URL for the new Request object.	required
content	Optional[Union[str, bytes, Iterable[bytes], AsyncIterable[bytes]]]	Content to send in the body of the Request.	None
data	Optional[Mapping[str, Any]]	Dictionary, list of tuples, bytes, or file-like object to send in the body of the Request.	None
json	Optional[Any]	A JSON serializable Python object to send in the body of the Request.	None
params	Optional[Mapping[str, Any]]	Dictionary, list of tuples or bytes to send in the query string for the Request.	None
**kwargs	Any	Additional arguments to send to the request method.	{}

Returns:

Type	Description
Response

Examples:

A recent use of this method was to delete a Tag (which isn't available via the Developer API yet)

import lunchable

lunch = lunchable.LunchMoney()

# Get All the Tags
all_tags = lunch.get_tags()
# Get All The Null Tags (a list of 1 or zero)
null_tags = [tag for tag in all_tags if tag.name in [None, ""]]

# Create a Cookie dictionary from a browser session
cookies = {"cookie_keys": "cookie_values"}
del lunch.session.headers["authorization"]

for null_tag in null_tags:
    # use the httpx.client embedded in the class to make a request with cookies
    response = lunch.request(
        method=lunch.Methods.DELETE,
        url=f"https://api.lunchmoney.app/tags/{null_tag.id}",
        cookies=cookies
    )
    # raise an error for 4XX responses
    response.raise_for_status()

trigger_fetch_from_plaid(start_date=None, end_date=None, plaid_account_id=None)

Trigger Fetch from Plaid

** This is an experimental endpoint and parameters and/or response may change. **

Use this endpoint to trigger a fetch for latest data from Plaid.

Returns true if there were eligible Plaid accounts to trigger a fetch for. Eligible accounts are those who last_fetch value is over 1 minute ago. (Although the limit is every minute, please use this endpoint sparingly!)

Note that fetching from Plaid is a background job. This endpoint simply queues up the job. You may track the plaid_last_successful_update, last_fetch and last_import properties to verify the results of the fetch.

Parameters:

Name	Type	Description	Default
start_date	Optional[date]	Start date for fetch (ignored if end_date is null)	None
end_date	Optional[date]	End date for fetch (ignored if start_date is null)	None
plaid_account_id	Optional[int]	Specific ID of a plaid account to fetch. If left empty, endpoint will trigger a fetch for all eligible accounts	None

Returns:

Type	Description
bool	Returns true if there were eligible Plaid accounts to trigger a fetch for.

unsplit_transactions(parent_ids, remove_parents=None)

Unsplit Transactions

Use this endpoint to unsplit one or more transactions.

Returns an array of IDs of deleted transactions

https://lunchmoney.dev/#unsplit-transactions

Parameters:

Name	Type	Description	Default
parent_ids	List[int]	Array of transaction IDs to unsplit. If one transaction is unsplittable, no transaction will be unsplit.	required
remove_parents	Optional[bool]	If true, deletes the original parent transaction as well. Note, this is unreversable!	None

Returns:

Type	Description
List[int]

update_asset(asset_id, type_name=None, subtype_name=None, name=None, balance=None, balance_as_of=None, currency=None, institution_name=None)

Update a Single Asset

Parameters:

Name	Type	Description	Default
asset_id	int	Asset Identifier	required
type_name	Optional[str]	Must be one of: cash, credit, investment, other, real estate, loan, vehicle, cryptocurrency, employee compensation	None
subtype_name	Optional[str]	Max 25 characters	None
name	Optional[str]	Max 45 characters	None
balance	Optional[float]	Numeric value of the current balance of the account. Do not include any special characters aside from a decimal point!	None
balance_as_of	Optional[datetime]	Has no effect if balance is not defined. If balance is defined, but balance_as_of is not supplied or is invalid, current timestamp will be used.	None
currency	Optional[str]	Three-letter lowercase currency in ISO 4217 format. The code sent must exist in our database. Defaults to asset's currency.	None
institution_name	Optional[str]	Max 50 characters	None

Returns:

Type	Description
AssetsObject

update_category(category_id, name=None, description=None, is_income=None, exclude_from_budget=None, exclude_from_totals=None, group_id=None, archived=None)

Update a single category

Use this endpoint to update the properties for a single category or category group

https://lunchmoney.dev/#update-category

Parameters:

Name	Type	Description	Default
category_id	int	Id of the Lunch Money Category	required
name	Optional[str]	Name of category. Must be between 1 and 40 characters.	None
description	Optional[str]	Description of category. Must be less than 140 categories. Defaults to None.	None
is_income	Optional[bool]	Whether or not transactions in this category should be treated as income. Defaults to False.	None
exclude_from_budget	Optional[bool]	Whether or not transactions in this category should be excluded from budgets. Defaults to False.	None
exclude_from_totals	Optional[bool]	Whether or not transactions in this category should be excluded from calculated totals. Defaults to False.	None
group_id	Optional[int]	For a category, set the group_id to include it in a category group	None
archived	Optional[bool]	Whether or not category should be archived.	None

Returns:

Type	Description
bool

update_crypto(crypto_id, name=None, display_name=None, institution_name=None, balance=None, currency=None)

Update a Manual Crypto Asset

Use this endpoint to update a single manually-managed crypto asset (does not include assets received from syncing with your wallet/exchange/etc). These are denoted by source: manual from the GET call above.

https://lunchmoney.dev/#update-manual-crypto-asset

Parameters:

Name	Type	Description	Default
crypto_id	int	ID of the crypto asset to update	required
name	Optional[str]	Official or full name of the account. Max 45 characters	None
display_name	Optional[str]	Display name for the account. Max 25 characters	None
institution_name	Optional[str]	Name of provider that holds the account. Max 50 characters	None
balance	Optional[float]	Numeric value of the current balance of the account. Do not include any special characters aside from a decimal point!	None
currency	Optional[str]	Cryptocurrency that is supported for manual tracking in our database	None

Returns:

Type	Description
CryptoObject

update_transaction(transaction_id, transaction=None, split=None, debit_as_negative=None, skip_balance_update=None)

Update a Transaction

Use this endpoint to update a single transaction. You may also use this to split an existing transaction. If a TransactionObject is provided it will be converted into a TransactionUpdateObject.

PUT https://dev.lunchmoney.app/v1/transactions/:transaction_id

Parameters:

Name	Type	Description	Default
transaction_id	int	Lunch Money Transaction ID	required
transaction	ListOrSingleTransactionUpdateObject	Object to update with	None
split	Optional[List[TransactionSplitObject]]	Defines the split of a transaction. You may not split an already-split transaction, recurring transaction, or group transaction.	None
debit_as_negative	Optional[bool]	If true, will assume negative amount values denote expenses and positive amount values denote credits. Defaults to false.	None
skip_balance_update	Optional[bool]	If false, will skip updating balance if an asset_id is present for any of the transactions.	None

Returns:

Type	Description
Dict[str, Any]

Examples:

Update a transaction with a TransactionUpdateObject

from datetime import datetime

from lunchable import LunchMoney, TransactionUpdateObject

lunch = LunchMoney(access_token="xxxxxxx")
transaction_note = f"Updated on {datetime.now()}"
notes_update = TransactionUpdateObject(notes=transaction_note)
response = lunch.update_transaction(transaction_id=1234,
                                    transaction=notes_update)

Update a TransactionObject with itself

from datetime import datetime, timedelta

from lunchable import LunchMoney

lunch = LunchMoney(access_token="xxxxxxx")
transaction = lunch.get_transaction(transaction_id=1234)

transaction.notes = f"Updated on {datetime.now()}"
transaction.date = transaction.date + timedelta(days=1)
response = lunch.update_transaction(transaction_id=transaction.id,
                                    transaction=transaction)

upsert_budget(start_date, category_id, amount, currency=None)

Upsert a Budget for a Category and Date

Use this endpoint to update an existing budget or insert a new budget for a particular category and date.

Note: Lunch Money currently only supports monthly budgets, so your date must always be the start of a month (eg. 2021-04-01)

If this is a sub-category, the response will include the updated category group's budget. This is because setting a sub-category may also update the category group's overall budget.

https://lunchmoney.dev/#upsert-budget

Parameters:

Name	Type	Description	Default
start_date	date	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)	required
category_id	int	Unique identifier for the category	required
amount	float	Amount for budget	required
currency	Optional[str]	Currency for the budgeted amount (optional). If empty, will default to your primary currency	None

Returns:

Type	Description
Optional[Dict[str, Any]]