recurring_items

Lunch Money - Recurring Expenses

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

RecurringItemsClient

Bases: LunchMoneyAPIClient

Lunch Money Recurring Items Interactions

Source code in lunchable/models/recurring_items.py

class RecurringItemsClient(LunchMoneyAPIClient):
    """
    Lunch Money Recurring Items Interactions
    """

    def get_recurring_items(
        self,
        start_date: Optional[datetime.date] = None,
        debit_as_negative: Optional[bool] = None,
    ) -> List[RecurringItemsObject]:
        """
        Get Recurring Items

        Use this to retrieve a list of recurring items to expect for a specified month.

        A different set of recurring items is expected every month. These can be once a year,
        twice a year, every four months, etc.

        If a recurring item is listed as “twice a month,” then the recurring item object returned
        will have an occurrences attribute populated by the different billing dates the system believes
        recurring transactions should occur, including the two dates in the current month, the last
        transaction date prior to the month, and the next transaction date after the month.

        If the recurring item is listed as “once a week,” then the recurring item object returned will
        have an occurrences object populated with as many times as there are weeks for the specified
        month, along with the last transaction from the previous month and the next transaction for
        the next month.

        In the same vein, if a recurring item that began last month is set to “Every 3 months”,
        then that recurring item object that occurred will not include any dates for this month.

        Parameters
        ----------
        start_date : Optional[datetime.date]
            Date to search. Whatever your start date, the system will automatically
            return recurring items expected for that month. For instance, if you
            input 2020-01-25, the system will return recurring items which are to
            be expected between 2020-01-01 to 2020-01-31. By default will return
            the first day of the current month
        debit_as_negative: bool
            Pass in true if you'd like items to be returned as negative amounts
            and credits as positive amounts. Defaults to false.

        Returns
        -------
        List[RecurringItemsObject]
        """
        if start_date is None:
            start_date = datetime.datetime.now().date().replace(day=1)
        params = RecurringItemsParamsGet(
            start_date=start_date, debit_as_negative=debit_as_negative
        ).model_dump(exclude_none=True)
        response_data = self.make_request(
            method=self.Methods.GET,
            url_path=[APIConfig.LUNCH_MONEY_RECURRING_ITEMS],
            params=params,
        )
        recurring_expenses_objects = [
            RecurringItemsObject.model_validate(item) for item in response_data
        ]
        logger.debug(
            "%s RecurringExpensesObjects retrieved", len(recurring_expenses_objects)
        )
        return recurring_expenses_objects

get_recurring_items(start_date=None, debit_as_negative=None)

Get Recurring Items

Use this to retrieve a list of recurring items to expect for a specified month.

A different set of recurring items is expected every month. These can be once a year, twice a year, every four months, etc.

If a recurring item is listed as “twice a month,” then the recurring item object returned will have an occurrences attribute populated by the different billing dates the system believes recurring transactions should occur, including the two dates in the current month, the last transaction date prior to the month, and the next transaction date after the month.

If the recurring item is listed as “once a week,” then the recurring item object returned will have an occurrences object populated with as many times as there are weeks for the specified month, along with the last transaction from the previous month and the next transaction for the next month.

In the same vein, if a recurring item that began last month is set to “Every 3 months”, then that recurring item object that occurred will not include any dates for this month.

Parameters:

Name	Type	Description	Default
start_date	Optional[date]	Date to search. Whatever your start date, the system will automatically return recurring items expected for that month. For instance, if you input 2020-01-25, the system will return recurring items which are to be expected between 2020-01-01 to 2020-01-31. By default will return the first day of the current month	None
debit_as_negative	Optional[bool]	Pass in true if you'd like items to be returned as negative amounts and credits as positive amounts. Defaults to false.	None

Returns:

Type	Description
List[RecurringItemsObject]

Source code in lunchable/models/recurring_items.py

def get_recurring_items(
    self,
    start_date: Optional[datetime.date] = None,
    debit_as_negative: Optional[bool] = None,
) -> List[RecurringItemsObject]:
    """
    Get Recurring Items

    Use this to retrieve a list of recurring items to expect for a specified month.

    A different set of recurring items is expected every month. These can be once a year,
    twice a year, every four months, etc.

    If a recurring item is listed as “twice a month,” then the recurring item object returned
    will have an occurrences attribute populated by the different billing dates the system believes
    recurring transactions should occur, including the two dates in the current month, the last
    transaction date prior to the month, and the next transaction date after the month.

    If the recurring item is listed as “once a week,” then the recurring item object returned will
    have an occurrences object populated with as many times as there are weeks for the specified
    month, along with the last transaction from the previous month and the next transaction for
    the next month.

    In the same vein, if a recurring item that began last month is set to “Every 3 months”,
    then that recurring item object that occurred will not include any dates for this month.

    Parameters
    ----------
    start_date : Optional[datetime.date]
        Date to search. Whatever your start date, the system will automatically
        return recurring items expected for that month. For instance, if you
        input 2020-01-25, the system will return recurring items which are to
        be expected between 2020-01-01 to 2020-01-31. By default will return
        the first day of the current month
    debit_as_negative: bool
        Pass in true if you'd like items to be returned as negative amounts
        and credits as positive amounts. Defaults to false.

    Returns
    -------
    List[RecurringItemsObject]
    """
    if start_date is None:
        start_date = datetime.datetime.now().date().replace(day=1)
    params = RecurringItemsParamsGet(
        start_date=start_date, debit_as_negative=debit_as_negative
    ).model_dump(exclude_none=True)
    response_data = self.make_request(
        method=self.Methods.GET,
        url_path=[APIConfig.LUNCH_MONEY_RECURRING_ITEMS],
        params=params,
    )
    recurring_expenses_objects = [
        RecurringItemsObject.model_validate(item) for item in response_data
    ]
    logger.debug(
        "%s RecurringExpensesObjects retrieved", len(recurring_expenses_objects)
    )
    return recurring_expenses_objects

RecurringItemsObject

Bases: LunchableModel

Recurring Expenses Object

Parameters:

Name	Type	Description	Default
id	int	Unique identifier for recurring item	required
start_date	date | None	Denotes when recurring item starts occurring in ISO 8601 format. If null, then this recurring item will show up for all time before end_date	None
end_date	date | None	Denotes when recurring item stops occurring in ISO 8601 format. If null, then this recurring item has no set end date and will show up for all months after start_date	None
payee	str	Payee or payer of the recurring item	required
currency	str	Three-letter lowercase currency code for the recurring item in ISO 4217 format	required
created_by	int	The id of the user who created this recurring item.	required
created_at	datetime	The date and time of when the recurring item was created (in the ISO 8601 extended format).	required
updated_at	datetime	The date and time of when the recurring item was updated (in the ISO 8601 extended format).	required
billing_date	date	Initial date that a transaction associated with this recurring item occured. This date is used in conjunction with values of quantity and granularity to determine the expected dates of recurring transactions in the period.	required
original_name	str | None	If any, represents the original name of the recurring item as denoted by the transaction that triggered its creation	None
description	str | None	If any, represents the user-entered description of the recurring item	None
plaid_account_id	int | None	If any, denotes the plaid account associated with the creation of this recurring item (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 item (see Assets)	None
source	str	This can be one of four values: - manual: User created this recurring item manually from the Recurring Items page - transaction: User created this by converting a transaction from the Transactions page - system: Recurring item was created by the system on transaction import - null: Some older recurring items may not have a source.	required
notes	str | None	If any, the user-entered notes for the recurring item	None
amount	float	Amount of the recurring item in numeric format to 4 decimal places. For recurring items with flexible amounts, this is the average of the specified min and max amounts.	required
category_id	int | None	If any, denotes the unique identifier for the associated category to this recurring item	None
category_group_id	int | None	If any, denotes the unique identifier of associated category group	None
is_income	bool	Based on the associated category's property, denotes if the recurring transaction is treated as income	required
exclude_from_totals	bool	Based on the associated category's property, denotes if the recurring transaction is excluded from totals	required
granularity	str	The unit of time used to define the cadence of the recurring item. One of weeks, months, years	required
cadence	str | None		None
quantity	int | None	The number of granular units between each occurrence	None
occurrences	Dict[date, List[SummarizedTransactionObject]]	An object which contains dates as keys and lists as values. The dates will include all the dates in the month that a recurring item is expected, as well as the last date in the previous period and the first date in the next period. The value for each key is a list of Summarized Transaction Objects that matched the recurring item for that date (if any)	required
transactions_within_range	List[SummarizedTransactionObject] | None	A list of all the Summarized Transaction Objects for transactions that that have occurred in the query month for the recurring item (if any)	None
missing_dates_within_range	List[Any] | None	A list of date strings when a recurring transaction is expected but has not (yet) occurred.	None
date	date | None	Denotes the value of the start_date query parameter, or if none was provided, the date when the request was made. This indicates the month used by the system when populating the response.	None
to_base	float	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.	required

Source code in lunchable/models/recurring_items.py

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

    id: int = Field(description=_RecurringItemsDescriptions.id)
    start_date: Optional[datetime.date] = Field(
        None, description=_RecurringItemsDescriptions.start_date
    )
    end_date: Optional[datetime.date] = Field(
        None, description=_RecurringItemsDescriptions.end_date
    )
    payee: str = Field(description=_RecurringItemsDescriptions.payee)
    currency: str = Field(
        max_length=3, description=_RecurringItemsDescriptions.currency
    )
    created_by: int = Field(description=_RecurringItemsDescriptions.created_by)
    created_at: datetime.datetime = Field(
        description=_RecurringItemsDescriptions.created_at
    )
    updated_at: datetime.datetime = Field(
        description=_RecurringItemsDescriptions.updated_at
    )
    billing_date: datetime.date = Field(
        description=_RecurringItemsDescriptions.billing_date
    )
    original_name: Optional[str] = Field(
        None, description=_RecurringItemsDescriptions.original_name
    )
    description: Optional[str] = Field(
        None, description=_RecurringItemsDescriptions.description
    )
    plaid_account_id: Optional[int] = Field(
        None, description=_RecurringItemsDescriptions.plaid_account_id
    )
    asset_id: Optional[int] = Field(
        None, description=_RecurringItemsDescriptions.asset_id
    )
    source: str = Field(description=_RecurringItemsDescriptions.source)
    notes: Optional[str] = Field(None, description=_RecurringItemsDescriptions.notes)
    amount: float = Field(description=_RecurringItemsDescriptions.amount)
    category_id: Optional[int] = Field(
        None, description=_RecurringItemsDescriptions.category_id
    )
    category_group_id: Optional[int] = Field(
        None, description=_RecurringItemsDescriptions.category_group_id
    )
    is_income: bool = Field(description=_RecurringItemsDescriptions.is_income)
    exclude_from_totals: bool = Field(
        description=_RecurringItemsDescriptions.exclude_from_totals
    )
    granularity: str = Field(description=_RecurringItemsDescriptions.granularity)
    cadence: Optional[str] = Field(None)
    quantity: Optional[int] = Field(
        None, description=_RecurringItemsDescriptions.quantity
    )
    occurrences: Dict[datetime.date, List[SummarizedTransactionObject]] = Field(
        description=_RecurringItemsDescriptions.occurrences
    )
    transactions_within_range: Optional[List[SummarizedTransactionObject]] = Field(
        None, description=_RecurringItemsDescriptions.transactions_within_range
    )
    missing_dates_within_range: Optional[List[Any]] = Field(
        None, description=_RecurringItemsDescriptions.missing_dates_within_range
    )
    date: Optional[datetime.date] = Field(
        None, description=_RecurringItemsDescriptions.date
    )
    to_base: float = Field(description=_RecurringItemsDescriptions.to_base)

RecurringItemsParamsGet

Bases: LunchableModel

https://lunchmoney.dev/#get-recurring-items

Parameters:

Name	Type	Description	Default
start_date	date		required
debit_as_negative	bool | None		None

Source code in lunchable/models/recurring_items.py

class RecurringItemsParamsGet(LunchableModel):
    """
    https://lunchmoney.dev/#get-recurring-items
    """

    start_date: datetime.date
    debit_as_negative: Optional[bool] = None

SummarizedTransactionObject

Bases: LunchableModel

Summarized Transaction Object

Parameters:

Name	Type	Description	Default
id	int	Unique identifier for the transaction that matched this recurring item	required
date	date	Date of transaction in ISO 8601 format	required
amount	float	Amount of the transaction in numeric format to 4 decimal places	required
currency	str	Three-letter lowercase currency code of the transaction in ISO 4217 format	required
payee	str	Payee or payer of the recurring item	required
category_id	int | None	Unique identifier of associated category	None
recurring_id	int | None	Unique identifier of associated recurring item	None
to_base	float	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.	required

Source code in lunchable/models/recurring_items.py

class SummarizedTransactionObject(LunchableModel):
    """
    Summarized Transaction Object
    """

    id: int = Field(description=_SummarizedTransactionDescriptions.id)
    date: datetime.date = Field(description=_SummarizedTransactionDescriptions.date)
    amount: float = Field(description=_SummarizedTransactionDescriptions.amount)
    currency: str = Field(
        max_length=3, description=_SummarizedTransactionDescriptions.currency
    )
    payee: str = Field(description=_SummarizedTransactionDescriptions.payee)
    category_id: Optional[int] = Field(
        None, description=_SummarizedTransactionDescriptions.category_id
    )
    recurring_id: Optional[int] = Field(
        None, description=_SummarizedTransactionDescriptions.recurring_id
    )
    to_base: float = Field(description=_SummarizedTransactionDescriptions.to_base)