models

Lunch Money Python SDK and Associated Objects

AssetsObject

Bases: LunchableModel

Manually Managed Asset Objects

Assets in Lunch Money are similar to plaid-accounts except that they are manually managed.

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

Parameters:

Name	Type	Description	Default
id	int	Unique identifier for asset	required
type_name	str	Primary type of the asset. Must be one of: [employee compensation, cash, vehicle, loan, cryptocurrency, investment, other, credit, real estate]	required
subtype_name	str | None	Optional asset subtype. Examples include: [retirement, checking, savings, prepaid credit card]	None
name	str	Name of the asset	required
display_name	str | None	Display name of the asset (as set by user)	None
balance	float	Current balance of the asset in numeric format to 4 decimal places"	required
balance_as_of	datetime | None	Date/time the balance was last updated in ISO 8601 extended format	None
closed_on	date | None	The date this asset was closed (optional)	None
currency	str	Three-letter lowercase currency code of the balance in ISO 4217 format	required
institution_name	str | None	Name of institution holding the asset	None
exclude_transactions	bool	If true, this asset will not show up as an option for assignment when creating transactions manually	False
created_at	datetime	Date/time the asset was created in ISO 8601 extended format	required

Source code in lunchable/models/assets.py

class AssetsObject(LunchableModel):
    """
    Manually Managed Asset Objects

    Assets in Lunch Money are similar to `plaid-accounts` except that they are manually managed.

    https://lunchmoney.dev/#assets-object
    """

    id: int = Field(description="Unique identifier for asset")
    type_name: str = Field(description=_AssetsDescriptions.type_name)
    subtype_name: Optional[str] = Field(
        None, description=_AssetsDescriptions.subtype_name
    )
    name: str = Field(description="Name of the asset")
    display_name: Optional[str] = Field(
        None, description="Display name of the asset (as set by user)"
    )
    balance: float = Field(description=_AssetsDescriptions.balance)
    balance_as_of: Optional[datetime.datetime] = Field(
        None, description=_AssetsDescriptions.balance_as_of
    )
    closed_on: Optional[datetime.date] = Field(
        None, description=_AssetsDescriptions.closed_on
    )
    currency: str = Field(description=_AssetsDescriptions.currency)
    institution_name: Optional[str] = Field(
        None, description="Name of institution holding the asset"
    )
    exclude_transactions: bool = Field(
        default=False, description=_AssetsDescriptions.exclude_transactions
    )
    created_at: datetime.datetime = Field(description=_AssetsDescriptions.created_at)

BudgetObject

Bases: LunchableModel

Monthly Budget Per Category Object

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

Parameters:

Name	Type	Description	Default
category_name	str	Name of the category	required
category_id	int | None	Unique identifier for category	None
category_group_name	str | None	Name of the category group, if applicable	None
group_id	int | None	Unique identifier for category group	None
is_group	bool | None	If true, this category is a group	None
is_income	bool	If true, this category is an income category (category properties are set in the app via the Categories page)	required
exclude_from_budget	bool	If true, this category is excluded from budget (category properties are set in the app via the Categories page)	required
exclude_from_totals	bool	If true, this category is excluded from totals (category properties are set in the app via the Categories page)	required
data	Dict[date, BudgetDataObject]	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.	required
config	BudgetConfigObject | None	Object representing the category's budget suggestion configuration	None

Source code in lunchable/models/budgets.py

class BudgetObject(LunchableModel):
    """
    Monthly Budget Per Category Object

    https://lunchmoney.dev/#budget-object
    """

    category_name: str = Field(description="Name of the category")
    category_id: Optional[int] = Field(
        None, description="Unique identifier for category"
    )
    category_group_name: Optional[str] = Field(
        None, description=_BudgetDescriptions.category_group_name
    )
    group_id: Optional[int] = Field(
        None, description="Unique identifier for category group"
    )
    is_group: Optional[bool] = Field(
        None, description="If true, this category is a group"
    )
    is_income: bool = Field(description=_BudgetDescriptions.is_income)
    exclude_from_budget: bool = Field(
        description=_BudgetDescriptions.exclude_from_budget
    )
    exclude_from_totals: bool = Field(
        description=_BudgetDescriptions.exclude_from_totals
    )
    data: Dict[datetime.date, BudgetDataObject] = Field(
        description=_BudgetDescriptions.data
    )
    config: Optional[BudgetConfigObject] = Field(
        None, description=_BudgetDescriptions.config
    )

CategoriesObject

Bases: LunchableModel

Lunch Money Spending Categories

https://lunchmoney.dev/#categories-object

Parameters:

Name	Type	Description	Default
id	int	A unique identifier for the category.	required
name	str	The name of the category. Must be between 1 and 40 characters.	required
description	str | None	The description of the category. Must not exceed 140 characters.	None
is_income	bool	If true, the transactions in this category will be treated as income.	required
exclude_from_budget	bool	If true, the transactions in this category will be excluded from the budget.	required
exclude_from_totals	bool	If true, the transactions in this category will be excluded from totals.	required
archived	bool	If true, the category is archived and not displayed in relevant areas of the Lunch Money app.	False
archived_on	datetime | None	The date and time of when the category was last archived (in the ISO 8601 extended format).	None
updated_at	datetime | None	The date and time of when the category was last updated (in the ISO 8601 extended format).	None
created_at	datetime | None	The date and time of when the category was created (in the ISO 8601 extended format).	None
is_group	bool	If true, the category is a group that can be a parent to other categories.	required
group_id	int | None	The ID of a category group (or null if the category doesn't belong to a category group).	None
order	int | None	Numerical ordering of categories	None
children	List[Union[CategoriesObject, CategoryChild]] | None	For category groups, this will populate with the categories nested within and include id, name, description and created_at fields.	None

Source code in lunchable/models/categories.py

class CategoriesObject(LunchableModel):
    """
    Lunch Money Spending Categories

    https://lunchmoney.dev/#categories-object
    """

    id: int = Field(description="A unique identifier for the category.")
    name: str = Field(
        min_length=1,
        max_length=40,
        description=_CategoriesDescriptions.name,
    )
    description: Optional[str] = Field(
        None, max_length=140, description=_CategoriesDescriptions.description
    )
    is_income: bool = Field(description=_CategoriesDescriptions.is_income)
    exclude_from_budget: bool = Field(
        description=_CategoriesDescriptions.exclude_from_budget
    )
    exclude_from_totals: bool = Field(
        description=_CategoriesDescriptions.exclude_from_totals
    )
    archived: bool = Field(False, description=_CategoriesDescriptions.archived)
    archived_on: Optional[datetime.datetime] = Field(
        None, description=_CategoriesDescriptions.archived_on
    )
    updated_at: Optional[datetime.datetime] = Field(
        None, description=_CategoriesDescriptions.updated_at
    )
    created_at: Optional[datetime.datetime] = Field(
        None, description=_CategoriesDescriptions.created_at
    )
    is_group: bool = Field(description=_CategoriesDescriptions.is_group)
    group_id: Optional[int] = Field(None, description=_CategoriesDescriptions.group_id)
    order: Optional[int] = Field(None, description=_CategoriesDescriptions.order)
    children: Optional[List[Union[CategoriesObject, CategoryChild]]] = Field(
        None,
        description=_CategoriesDescriptions.children,
    )

CryptoObject

Bases: LunchableModel

Crypto Asset Object

https://lunchmoney.dev/#crypto-object

Parameters:

Name	Type	Description	Default
id	int	Unique identifier for a manual crypto account (no ID for synced accounts)	required
zabo_account_id	int | None	Unique identifier for a synced crypto account (no ID for manual accounts, multiple currencies may have the same zabo_account_id)	None
source	str	synced (this account is synced via a wallet, exchange, etc.) or manual (this account balance is managed manually)	required
name	str	Name of the crypto asset	required
display_name	str | None	Display name of the crypto asset (as set by user)	None
balance	float	Current balance	required
balance_as_of	datetime | None	Date/time the balance was last updated in ISO 8601 extended format	None
currency	str | None	Abbreviation for the cryptocurrency	None
status	str | None	The current status of the crypto account. Either active or in error.	None
institution_name	str | None	Name of provider holding the asset	None
created_at	datetime	Date/time the asset was created in ISO 8601 extended format	required

Source code in lunchable/models/crypto.py

class CryptoObject(LunchableModel):
    """
    Crypto Asset Object

    https://lunchmoney.dev/#crypto-object
    """

    id: int = Field(description=_CryptoDescriptions.id)
    zabo_account_id: Optional[int] = Field(
        None, description=_CryptoDescriptions.zabo_account_id
    )
    source: str = Field(description=_CryptoDescriptions.source)
    name: str = Field(description="Name of the crypto asset")
    display_name: Optional[str] = Field(
        None, description=_CryptoDescriptions.display_name
    )
    balance: float = Field(description="Current balance")
    balance_as_of: Optional[datetime.datetime] = Field(
        None, description=_CryptoDescriptions.balance_as_of
    )
    currency: Optional[str] = Field(
        None, description="Abbreviation for the cryptocurrency"
    )
    status: Optional[str] = Field(None, description=_CryptoDescriptions.status)
    institution_name: Optional[str] = Field(
        default=None, description="Name of provider holding the asset"
    )
    created_at: datetime.datetime = Field(description=_CryptoDescriptions.created_at)

LunchableModel

Bases: BaseModel

Hashable Pydantic Model

Source code in lunchable/models/_base.py

class LunchableModel(BaseModel):
    """
    Hashable Pydantic Model
    """

    model_config = ConfigDict(extra="allow")

    def __hash__(self) -> int:
        """
        Hash Method for Pydantic BaseModels
        """
        return hash((type(self), *tuple(self.__dict__.values())))

__hash__()

Hash Method for Pydantic BaseModels

Source code in lunchable/models/_base.py

def __hash__(self) -> int:
    """
    Hash Method for Pydantic BaseModels
    """
    return hash((type(self), *tuple(self.__dict__.values())))

PlaidAccountObject

Bases: LunchableModel

Assets synced from Plaid

Similar to AssetObjects, these accounts are linked to remote sources in Plaid.

https://lunchmoney.dev/#plaid-accounts-object

Parameters:

Name	Type	Description	Default
id	int	Unique identifier of Plaid account	required
date_linked	date	Date account was first linked in ISO 8601 extended format	required
name	str	Name of the account. Can be overridden by the user. Field is originally set by Plaid	required
type	str	Primary type of account. Typically one of: [credit, depository, brokerage, cash, loan, investment]. This field is set by Plaid and cannot be altered.	required
subtype	str	Optional subtype name of account. This field is set by Plaid and cannot be altered	required
mask	str | None	Mask (last 3 to 4 digits of account) of account. This field is set by Plaid and cannot be altered	None
institution_name	str	Name of institution associated with account. This field is set by Plaid and cannot be altered	required
status	str	Denotes the current status of the account within Lunch Money. Must be one of: active (Account is active and in good state), inactive (Account marked inactive from user. No transactions fetched or balance update for this account), relink (Account needs to be relinked with Plaid), syncing (Account is awaiting first import of transactions), error (Account is in error with Plaid), not found (Account is in error with Plaid), not supported (Account is in error with Plaid)	required
last_import	datetime | None	Date of last imported transaction in ISO 8601 extended format (not necessarily date of last attempted import)	None
balance	float | None	Current balance of the account in numeric format to 4 decimal places. This field is set by Plaid and cannot be altered	None
currency	str	Currency of account balance in ISO 4217 format. This field is set by Plaid and cannot be altered	required
balance_last_update	datetime	Date balance was last updated in ISO 8601 extended format. This field is set by Plaid and cannot be altered	required
limit	int | None	Optional credit limit of the account. This field is set by Plaid and cannot be altered	None

Source code in lunchable/models/plaid_accounts.py

class PlaidAccountObject(LunchableModel):
    """
    Assets synced from Plaid

    Similar to AssetObjects, these accounts are linked to remote sources in Plaid.

    https://lunchmoney.dev/#plaid-accounts-object
    """

    id: int = Field(description="Unique identifier of Plaid account")
    date_linked: datetime.date = Field(
        description=_PlaidAccountDescriptions.date_linked
    )
    name: str = Field(description=_PlaidAccountDescriptions.name)
    type: str = Field(description=_PlaidAccountDescriptions.type)
    subtype: str = Field(description=_PlaidAccountDescriptions.subtype)
    mask: Optional[str] = Field(None, description=_PlaidAccountDescriptions.mask)
    institution_name: str = Field(
        description=_PlaidAccountDescriptions.institution_name
    )
    status: str = Field(description=_PlaidAccountDescriptions.status)
    last_import: Optional[datetime.datetime] = Field(
        None, description=_PlaidAccountDescriptions.last_import
    )
    balance: Optional[float] = Field(
        None, description=_PlaidAccountDescriptions.balance
    )
    currency: str = Field(description=_PlaidAccountDescriptions.currency)
    balance_last_update: datetime.datetime = Field(
        description=_PlaidAccountDescriptions.balance_last_update
    )
    limit: Optional[int] = Field(None, description=_PlaidAccountDescriptions.limit)

RecurringExpensesObject

Bases: LunchableModel

Recurring Expenses Object

https://lunchmoney.dev/#recurring-expenses-object

Parameters:

Name	Type	Description	Default
id	int	Unique identifier for recurring expense	required
start_date	date | None	Denotes when recurring expense starts occurring in ISO 8601 format. If null, then this recurring expense will show up for all time before end_date	None
end_date	date | None	Denotes when recurring expense stops occurring in ISO 8601 format. If null, then this recurring expense has no set end date and will show up for all months after start_date	None
cadence	str	One of: [monthly, twice a month, once a week, every 3 months, every 4 months, twice a year, yearly]	required
payee	str	Payee of the recurring expense	required
amount	float	Amount of the recurring expense in numeric format to 4 decimal places	required
currency	str	Three-letter lowercase currency code for the recurring expense in ISO 4217 format	required
description	str | None	If any, represents the user-entered description of the recurring expense	None
billing_date	date	Expected billing date for this recurring expense for this month in ISO 8601 format	required
type	str	This can be one of two values: cleared (The recurring expense has been reviewed by the user), suggested (The recurring expense is suggested by the system; the user has yet to review/clear it)	required
original_name	str | None	If any, represents the original name of the recurring expense as denoted by the transaction that triggered its creation	None
source	str	This can be one of three values: manual (User created this recurring expense manually from the Recurring Expenses page), transaction (User created this by converting a transaction from the Transactions page), system (Recurring expense was created by the system on transaction import). Some older recurring expenses may not have a source.	required
plaid_account_id	int | None	If any, denotes the plaid account associated with the creation of this " recurring expense (see Plaid Accounts)	None
asset_id	int | None	If any, denotes the manually-managed account (i.e. asset) associated with the creation of this recurring expense (see Assets)	None
category_id	int | None	If any, denotes the unique identifier for the associated category to this recurring expense	None

Source code in lunchable/models/recurring_expenses.py

class RecurringExpensesObject(LunchableModel):
    """
    Recurring Expenses Object

    https://lunchmoney.dev/#recurring-expenses-object
    """

    id: int = Field(description=_RecurringExpensesDescriptions.id)
    start_date: Optional[datetime.date] = Field(
        None, description=_RecurringExpensesDescriptions.start_date
    )
    end_date: Optional[datetime.date] = Field(
        None, description=_RecurringExpensesDescriptions.end_date
    )
    cadence: str = Field(description=_RecurringExpensesDescriptions.cadence)
    payee: str = Field(description="Payee of the recurring expense")
    amount: float = Field(description=_RecurringExpensesDescriptions.amount)
    currency: str = Field(
        max_length=3, description=_RecurringExpensesDescriptions.currency
    )
    description: Optional[str] = Field(
        None, description=_RecurringExpensesDescriptions.description
    )
    billing_date: datetime.date = Field(
        description=_RecurringExpensesDescriptions.billing_date
    )
    type: str = Field(description=_RecurringExpensesDescriptions.type)
    original_name: Optional[str] = Field(
        None, description=_RecurringExpensesDescriptions.original_name
    )
    source: str = Field(description=_RecurringExpensesDescriptions.source)
    plaid_account_id: Optional[int] = Field(
        None, description=_RecurringExpensesDescriptions.plaid_account_id
    )
    asset_id: Optional[int] = Field(
        None, description=_RecurringExpensesDescriptions.asset_id
    )
    category_id: Optional[int] = Field(
        None, description=_RecurringExpensesDescriptions.category_id
    )

TagsObject

Bases: LunchableModel

Lunchmoney Tags object

https://lunchmoney.dev/#tags-object

Parameters:

Name	Type	Description	Default
id	int	Unique identifier for tag	required
name	str	User-defined name of tag	required
description	str | None	User-defined description of tag	None
archived	bool	If true, the tag will not show up when creating or updating transactions in the Lunch Money app	False

Source code in lunchable/models/tags.py

class TagsObject(LunchableModel):
    """
    Lunchmoney Tags object

    https://lunchmoney.dev/#tags-object
    """

    id: int = Field(description="Unique identifier for tag")
    name: str = Field(description="User-defined name of tag", min_length=1)
    description: Optional[str] = Field(
        None, description="User-defined description of tag"
    )
    archived: bool = Field(
        False,
        description=(
            "If true, the tag will not show up when creating or "
            "updating transactions in the Lunch Money app"
        ),
    )

TransactionBaseObject

Bases: LunchableModel

Base Model For All Transactions to Inherit From

Source code in lunchable/models/transactions.py

class TransactionBaseObject(LunchableModel):
    """
    Base Model For All Transactions to Inherit From
    """

    pass

TransactionInsertObject

Bases: TransactionBaseObject

Object For Creating New Transactions

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

Parameters:

Name	Type	Description	Default
date	date	Must be in ISO 8601 format (YYYY-MM-DD).	required
amount	float	Numeric value of amount. i.e. $4.25 should be denoted as 4.25.	required
category_id	int | None	Unique identifier for associated category_id. Category must be associated with the same account and must not be a category group.	None
payee	str | None	Max 140 characters	None
currency	str | None	Three-letter lowercase currency code in ISO 4217 format. The code sent must exist in our database. Defaults to user account's primary currency.	None
asset_id	int | None	Unique identifier for associated asset (manually-managed account). Asset must be associated with the same account.	None
recurring_id	int | None	Unique identifier for associated recurring expense. Recurring expense must be associated with the same account.	None
notes	str | None	Max 350 characters	None
status	StatusEnum | None	Must be either cleared or uncleared. If recurring_id is provided, the status will automatically be set to recurring or recurring_suggested depending on the type of recurring_id. Defaults to uncleared.	None
external_id	str | None	User-defined external ID for transaction. Max 75 characters. External IDs must be unique within the same asset_id.	None
tags	List[Union[str, int]] | None	Passing in a number will attempt to match by ID. If no matching tag ID is found, an error will be thrown. Passing in a string will attempt to match by string. If no matching tag name is found, a new tag will be created.	None

Source code in lunchable/models/transactions.py

class TransactionInsertObject(TransactionBaseObject):
    """
    Object For Creating New Transactions

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

    class StatusEnum(str, Enum):
        """
        Status Options, must be "cleared" or "uncleared"
        """

        cleared = "cleared"
        uncleared = "uncleared"

    date: datetime.date = Field(description=_TransactionInsertDescriptions.date)
    amount: float = Field(description=_TransactionInsertDescriptions.amount)
    category_id: Optional[int] = Field(
        None, description=_TransactionInsertDescriptions.category_id
    )
    payee: Optional[str] = Field(None, description="Max 140 characters", max_length=140)
    currency: Optional[str] = Field(
        None, description=_TransactionInsertDescriptions.currency, max_length=3
    )
    asset_id: Optional[int] = Field(
        None, description=_TransactionInsertDescriptions.asset_id
    )
    recurring_id: Optional[int] = Field(
        None, description=_TransactionInsertDescriptions.recurring_id
    )
    notes: Optional[str] = Field(None, description="Max 350 characters", max_length=350)
    status: Optional[StatusEnum] = Field(
        None, description=_TransactionInsertDescriptions.status
    )
    external_id: Optional[str] = Field(
        None, description=_TransactionInsertDescriptions.external_id, max_length=75
    )
    tags: Optional[List[Union[str, int]]] = Field(
        None, description=_TransactionInsertDescriptions.tags
    )

StatusEnum

Bases: str, Enum

Status Options, must be "cleared" or "uncleared"

Source code in lunchable/models/transactions.py

class StatusEnum(str, Enum):
    """
    Status Options, must be "cleared" or "uncleared"
    """

    cleared = "cleared"
    uncleared = "uncleared"

TransactionObject

Bases: TransactionBaseObject

Universal Lunch Money Transaction Object

https://lunchmoney.dev/#transaction-object

Parameters:

Name	Type	Description	Default
id	int	Unique identifier for transaction	required
date	date	Date of transaction in ISO 8601 format	required
payee	str | None	Name of payee. If recurring_id is not null, this field will show the payee of associated recurring expense instead of the original transaction payee	None
amount	float	Amount of the transaction in numeric format to 4 decimal places	required
currency	str | None	Three-letter lowercase currency code of the transaction in ISO 4217 format	None
to_base	float | None	The amount converted to the user's primary currency. If the multicurrency feature is not being used, to_base and amount will be the same.	None
category_id	int | None	Unique identifier of associated category	None
category_name	str | None	Name of category associated with transaction	None
category_group_id	int | None	Unique identifier of associated category group, if any	None
category_group_name	str | None	Name of category group associated with transaction, if any	None
is_income	bool | None	Based on the associated category's property, denotes if transaction is treated as income	None
exclude_from_budget	bool | None	Based on the associated category's property, denotes if transaction is excluded from budget	None
exclude_from_totals	bool | None	Based on the associated category's property, denotes if transaction is excluded from totals	None
created_at	datetime	The date and time of when the transaction was created (in the ISO 8601 extended format).	required
updated_at	datetime	The date and time of when the transaction was last updated (in the ISO 8601 extended format).	required
status	str | None	One of the following: cleared: User has reviewed the transaction uncleared: User has not yet reviewed the transaction recurring: Transaction is linked to a recurring expense recurring_suggested: Transaction is listed as a suggested transaction for an existing recurring expense. pending: Imported transaction is marked as pending. This should be a temporary state. User intervention is required to change this to recurring.	None
is_pending	bool | None	Denotes if transaction is pending (not posted)	None
notes	str | None	User-entered transaction notes If recurring_id is not null, this field will be description of associated recurring expense	None
original_name	str | None	The transactions original name before any payee name updates. For synced transactions, this is the raw original payee name from your bank.	None
recurring_id	int | None	Unique identifier of associated recurring item	None
recurring_payee	str | None	Payee name of associated recurring item	None
recurring_description	str | None	Description of associated recurring item	None
recurring_cadence	str | None	Cadence of associated recurring item (one of once a week, every 2 weeks, twice a month, monthly, every 2 months, every 3 months, every 4 months, twice a year, yearly)	None
recurring_type	str | None	Type of associated recurring (one of cleared, suggested, dismissed)	None
recurring_amount	float | None	Amount of associated recurring item	None
recurring_currency	str | None	Currency of associated recurring item	None
parent_id	int | None	Exists if this is a split transaction. Denotes the transaction ID of the original transaction. Note that the parent transaction is not returned in this call.	None
has_children	bool | None	True if this transaction is a parent transaction and is split into 2 or more other transactions	None
group_id	int | None	Exists if this transaction is part of a group. Denotes the parent’s transaction ID	None
is_group	bool | None	True if this transaction represents a group of transactions. If so, amount and currency represent the totalled amount of transactions bearing this transaction’s id as their group_id. Amount is calculated based on the user’s primary currency.	None
asset_id	int | None	Unique identifier of associated manually-managed account (see Assets) Note: plaid_account_id and asset_id cannot both exist for a transaction	None
asset_institution_name	str | None	Institution name of associated manually-managed account	None
asset_name	str | None	Name of associated manually-managed account	None
asset_display_name	str | None	Display name of associated manually-managed account	None
asset_status	str | None	Status of associated manually-managed account (one of active, closed)	None
plaid_account_id	int | None	Unique identifier of associated Plaid account (see Plaid Accounts) Note: plaid_account_id and asset_id cannot both exist for a transaction	None
plaid_account_name	str | None	Name of associated Plaid account	None
plaid_account_mask	str | None	Mask of associated Plaid account	None
institution_name	str | None	Institution name of associated Plaid account	None
plaid_account_display_name	str | None	Display name of associated Plaid account	None
plaid_metadata	Dict[str, Any] | None	Metadata associated with imported transaction from Plaid	None
source	str | None	Source of the transaction (one of api, csv, manual,merge,plaid, recurring,rule,user)	None
display_name	str | None	Display name for payee for transaction based on whether or not it is linked to a recurring item. If linked, returns recurring_payee field. Otherwise, returns the payee field.	None
display_notes	str | None	Display notes for transaction based on whether or not it is linked to a recurring item. If linked, returns recurring_notes field. Otherwise, returns the notes field.	None
account_display_name	str | None	Display name for associated account (manual or Plaid). If this is a synced account, returns plaid_account_display_name or asset_display_name.	None
tags	List[TagsObject] | None	Array of Tag objects	None
external_id	str | None	User-defined external ID for any manually-entered or imported transaction. External ID cannot be accessed or changed for Plaid-imported transactions. External ID must be unique by asset_id. Max 75 characters.	None
children	List[TransactionChildObject] | None	Array of Transaction objects. Only exists if this transaction is a parent transaction and is split into 2 or more other transactions. Child transactions do not contain all of the same fields as parent transactions.	None

Source code in lunchable/models/transactions.py

class TransactionObject(TransactionBaseObject):
    """
    Universal Lunch Money Transaction Object

    https://lunchmoney.dev/#transaction-object
    """

    id: int = Field(description=_TransactionDescriptions.id)
    date: datetime.date = Field(description=_TransactionDescriptions.date)
    payee: Optional[str] = Field(None, description=_TransactionDescriptions.payee)
    amount: float = Field(description=_TransactionDescriptions.amount)
    currency: Optional[str] = Field(
        None, max_length=3, description=_TransactionDescriptions.currency
    )
    to_base: Optional[float] = Field(None, description=_TransactionDescriptions.to_base)
    category_id: Optional[int] = Field(
        None, description=_TransactionDescriptions.category_id
    )
    category_name: Optional[str] = Field(
        None, description=_TransactionDescriptions.category_name
    )
    category_group_id: Optional[int] = Field(
        None, description=_TransactionDescriptions.category_group_id
    )
    category_group_name: Optional[str] = Field(
        None, description=_TransactionDescriptions.category_group_name
    )
    is_income: Optional[bool] = Field(
        None, description=_TransactionDescriptions.is_income
    )
    exclude_from_budget: Optional[bool] = Field(
        None, description=_TransactionDescriptions.exclude_from_budget
    )
    exclude_from_totals: Optional[bool] = Field(
        None, description=_TransactionDescriptions.exclude_from_totals
    )
    created_at: datetime.datetime = Field(
        description=_TransactionDescriptions.created_at
    )
    updated_at: datetime.datetime = Field(
        description=_TransactionDescriptions.updated_at
    )
    status: Optional[str] = Field(None, description=_TransactionDescriptions.status)
    is_pending: Optional[bool] = Field(
        None, description=_TransactionDescriptions.is_pending
    )
    notes: Optional[str] = Field(None, description=_TransactionDescriptions.notes)
    original_name: Optional[str] = Field(
        None, description=_TransactionDescriptions.original_name
    )
    recurring_id: Optional[int] = Field(
        None, description=_TransactionDescriptions.recurring_id
    )
    recurring_payee: Optional[str] = Field(
        None, description=_TransactionDescriptions.recurring_payee
    )
    recurring_description: Optional[str] = Field(
        None, description=_TransactionDescriptions.recurring_description
    )
    recurring_cadence: Optional[str] = Field(
        None, description=_TransactionDescriptions.recurring_cadence
    )
    recurring_type: Optional[str] = Field(
        None, description=_TransactionDescriptions.recurring_type
    )
    recurring_amount: Optional[float] = Field(
        None, description=_TransactionDescriptions.recurring_amount
    )
    recurring_currency: Optional[str] = Field(
        None, description=_TransactionDescriptions.recurring_currency
    )
    parent_id: Optional[int] = Field(
        None, description=_TransactionDescriptions.parent_id
    )
    has_children: Optional[bool] = Field(
        None, description=_TransactionDescriptions.has_children
    )
    group_id: Optional[int] = Field(None, description=_TransactionDescriptions.group_id)
    is_group: Optional[bool] = Field(
        None, description=_TransactionDescriptions.is_group
    )
    asset_id: Optional[int] = Field(None, description=_TransactionDescriptions.asset_id)
    asset_institution_name: Optional[str] = Field(
        None, description=_TransactionDescriptions.asset_institution_name
    )
    asset_name: Optional[str] = Field(
        None, description=_TransactionDescriptions.asset_name
    )
    asset_display_name: Optional[str] = Field(
        None, description=_TransactionDescriptions.asset_display_name
    )
    asset_status: Optional[str] = Field(
        None, description=_TransactionDescriptions.asset_status
    )
    plaid_account_id: Optional[int] = Field(
        None, description=_TransactionDescriptions.plaid_account_id
    )
    plaid_account_name: Optional[str] = Field(
        None, description=_TransactionDescriptions.plaid_account_name
    )
    plaid_account_mask: Optional[str] = Field(
        None, description=_TransactionDescriptions.plaid_account_mask
    )
    institution_name: Optional[str] = Field(
        None, description=_TransactionDescriptions.institution_name
    )
    plaid_account_display_name: Optional[str] = Field(
        None, description=_TransactionDescriptions.plaid_account_display_name
    )
    plaid_metadata: Optional[Dict[str, Any]] = Field(
        None, description=_TransactionDescriptions.plaid_metadata
    )
    source: Optional[str] = Field(None, description=_TransactionDescriptions.source)
    display_name: Optional[str] = Field(
        None, description=_TransactionDescriptions.display_name
    )
    display_notes: Optional[str] = Field(
        None, description=_TransactionDescriptions.display_notes
    )
    account_display_name: Optional[str] = Field(
        None, description=_TransactionDescriptions.account_display_name
    )
    tags: Optional[List[TagsObject]] = Field(None, description="Array of Tag objects")
    external_id: Optional[str] = Field(
        None, max_length=75, description=_TransactionDescriptions.external_id
    )
    children: Optional[List[TransactionChildObject]] = Field(
        None, description=_TransactionDescriptions.children
    )

    @field_validator("plaid_metadata", mode="before")
    def to_json(cls, x: Optional[str]) -> Optional[Dict[str, Any]]:
        """
        Check a result
        """
        if x is None:
            return None
        elif isinstance(x, dict):
            return x
        else:
            return pydantic_core.from_json(x)

    def get_update_object(self) -> TransactionUpdateObject:
        """
        Return a TransactionUpdateObject

        Return a TransactionUpdateObject to update an expense. Simply
        change one of the properties and perform an `update_transaction` with
        your Lunchable object.

        Returns
        -------
        TransactionUpdateObject
        """
        update_dict = self.model_dump()
        try:
            TransactionUpdateObject.StatusEnum(self.status)
        except ValueError:
            update_dict["status"] = None
        update_object = TransactionUpdateObject.model_validate(update_dict)
        if update_object.tags is not None:
            tags = [] if self.tags is None else self.tags
            update_object.tags = [tag.name for tag in tags]
        return update_object

    def get_insert_object(self) -> TransactionInsertObject:
        """
        Return a TransactionInsertObject

        Return a TransactionInsertObject to update an expense. Simply
        change some of the properties and perform an `insert_transactions` with
        your Lunchable object.

        Returns
        -------
        TransactionInsertObject
        """
        insert_dict = self.model_dump()
        try:
            TransactionInsertObject.StatusEnum(self.status)
        except ValueError:
            insert_dict["status"] = None
        insert_object = TransactionInsertObject.model_validate(insert_dict)
        if insert_object.tags is not None:
            tags = [] if self.tags is None else self.tags
            insert_object.tags = [tag.name for tag in tags]
        return insert_object

get_insert_object()

Return a TransactionInsertObject

Return a TransactionInsertObject to update an expense. Simply change some of the properties and perform an insert_transactions with your Lunchable object.

Returns:

Type	Description
TransactionInsertObject

Source code in lunchable/models/transactions.py

def get_insert_object(self) -> TransactionInsertObject:
    """
    Return a TransactionInsertObject

    Return a TransactionInsertObject to update an expense. Simply
    change some of the properties and perform an `insert_transactions` with
    your Lunchable object.

    Returns
    -------
    TransactionInsertObject
    """
    insert_dict = self.model_dump()
    try:
        TransactionInsertObject.StatusEnum(self.status)
    except ValueError:
        insert_dict["status"] = None
    insert_object = TransactionInsertObject.model_validate(insert_dict)
    if insert_object.tags is not None:
        tags = [] if self.tags is None else self.tags
        insert_object.tags = [tag.name for tag in tags]
    return insert_object

get_update_object()

Return a TransactionUpdateObject

Return a TransactionUpdateObject to update an expense. Simply change one of the properties and perform an update_transaction with your Lunchable object.

Returns:

Type	Description
TransactionUpdateObject

Source code in lunchable/models/transactions.py

def get_update_object(self) -> TransactionUpdateObject:
    """
    Return a TransactionUpdateObject

    Return a TransactionUpdateObject to update an expense. Simply
    change one of the properties and perform an `update_transaction` with
    your Lunchable object.

    Returns
    -------
    TransactionUpdateObject
    """
    update_dict = self.model_dump()
    try:
        TransactionUpdateObject.StatusEnum(self.status)
    except ValueError:
        update_dict["status"] = None
    update_object = TransactionUpdateObject.model_validate(update_dict)
    if update_object.tags is not None:
        tags = [] if self.tags is None else self.tags
        update_object.tags = [tag.name for tag in tags]
    return update_object

to_json(x)

Check a result

Source code in lunchable/models/transactions.py

@field_validator("plaid_metadata", mode="before")
def to_json(cls, x: Optional[str]) -> Optional[Dict[str, Any]]:
    """
    Check a result
    """
    if x is None:
        return None
    elif isinstance(x, dict):
        return x
    else:
        return pydantic_core.from_json(x)

TransactionSplitObject

Bases: TransactionBaseObject

Object for Splitting Transactions

https://lunchmoney.dev/#split-object

Parameters:

Name	Type	Description	Default
date	date	Must be in ISO 8601 format (YYYY-MM-DD).	required
category_id	int | None	Unique identifier for associated category_id. Category must be associated with the same account.	None
notes	str | None	Transaction Split Notes.	None
amount	float	Individual amount of split. Currency will inherit from parent transaction. All amounts must sum up to parent transaction amount.	required

Source code in lunchable/models/transactions.py

class TransactionSplitObject(TransactionBaseObject):
    """
    Object for Splitting Transactions

    https://lunchmoney.dev/#split-object
    """

    date: datetime.date = Field(description=_TransactionSplitDescriptions.date)
    category_id: Optional[int] = Field(
        default=None, description=_TransactionSplitDescriptions.category_id
    )
    notes: Optional[str] = Field(None, description=_TransactionSplitDescriptions.notes)
    amount: float = Field(description=_TransactionSplitDescriptions.amount)

TransactionUpdateObject

Bases: TransactionBaseObject

Object For Updating Existing Transactions

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

Parameters:

Name	Type	Description	Default
date	date | None	Must be in ISO 8601 format (YYYY-MM-DD).	None
category_id	int | None	Unique identifier for associated category_id. Category must be associated with the same account and must not be a category group.	None
payee	str | None	Max 140 characters	None
amount	float | None	You may only update this if this transaction was not created from an automatic import, i.e. if this transaction is not associated with a plaid_account_id	None
currency	str | None	You may only update this if this transaction was not created from an automatic import, i.e. if this transaction is not associated with a plaid_account_id. Defaults to user account's primary currency.	None
asset_id	int | None	Unique identifier for associated asset (manually-managed account). Asset must be associated with the same account. You may only update this if this transaction was not created from an automatic import, i.e. if this transaction is not associated with a plaid_account_id	None
recurring_id	int | None	Unique identifier for associated recurring expense. Recurring expense must be associated with the same account.	None
notes	str | None	Max 350 characters	None
status	StatusEnum | None	Must be either cleared or uncleared. Defaults to uncleared If recurring_id is provided, the status will automatically be set to recurring or recurring_suggested depending on the type of recurring_id. Defaults to uncleared.	None
external_id	str | None	User-defined external ID for transaction. Max 75 characters. External IDs must be unique within the same asset_id. You may only update this if this transaction was not created from an automatic import, i.e. if this transaction is not associated with a plaid_account_id	None
tags	List[Union[str, int]] | None	Passing in a number will attempt to match by ID. If no matching tag ID is found, an error will be thrown. Passing in a string will attempt to match by string. If no matching tag name is found, a new tag will be created.	None

Source code in lunchable/models/transactions.py

class TransactionUpdateObject(TransactionBaseObject):
    """
    Object For Updating Existing Transactions

    https://lunchmoney.dev/#update-transaction
    """

    class StatusEnum(str, Enum):
        """
        Status Options, must be "cleared" or "uncleared"
        """

        cleared = "cleared"
        uncleared = "uncleared"

    date: Optional[datetime.date] = Field(
        None, description=_TransactionUpdateDescriptions.date
    )
    category_id: Optional[int] = Field(
        None, description=_TransactionUpdateDescriptions.category_id
    )
    payee: Optional[str] = Field(None, description="Max 140 characters", max_length=140)
    amount: Optional[float] = Field(
        None, description=_TransactionUpdateDescriptions.amount
    )
    currency: Optional[str] = Field(
        None, description=_TransactionUpdateDescriptions.currency
    )
    asset_id: Optional[int] = Field(
        None, description=_TransactionUpdateDescriptions.asset_id
    )
    recurring_id: Optional[int] = Field(
        None, description=_TransactionUpdateDescriptions.recurring_id
    )
    notes: Optional[str] = Field(None, description="Max 350 characters", max_length=350)
    status: Optional[StatusEnum] = Field(
        None, description=_TransactionUpdateDescriptions.status
    )
    external_id: Optional[str] = Field(
        None, description=_TransactionUpdateDescriptions.external_id
    )
    tags: Optional[List[Union[int, str]]] = Field(
        None, description=_TransactionUpdateDescriptions.tags
    )

StatusEnum

Bases: str, Enum

Status Options, must be "cleared" or "uncleared"

Source code in lunchable/models/transactions.py

class StatusEnum(str, Enum):
    """
    Status Options, must be "cleared" or "uncleared"
    """

    cleared = "cleared"
    uncleared = "uncleared"

UserObject

Bases: LunchableModel

The LunchMoney User object

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

Parameters:

Name	Type	Description	Default
user_id	int	Unique identifier for user	required
user_name	str	User's' name	required
user_email	str	User's' Email	required
account_id	int	Unique identifier for the associated budgeting account	required
budget_name	str	Name of the associated budgeting account	required
api_key_label	str | None	User-defined label of the developer API key used. Returns null if nothing has been set.	None

Source code in lunchable/models/user.py

class UserObject(LunchableModel):
    """
    The LunchMoney `User` object

    https://lunchmoney.dev/#user-object
    """

    user_id: int = Field(description="Unique identifier for user")
    user_name: str = Field(description="User's' name")
    user_email: str = Field(description="User's' Email")
    account_id: int = Field(
        description="Unique identifier for the associated budgeting account"
    )
    budget_name: str = Field(description="Name of the associated budgeting account")
    api_key_label: Optional[str] = Field(
        None,
        description="User-defined label of the developer API key used. "
        "Returns null if nothing has been set.",
    )