Skip to content

recurring_expenses#

Lunch Money - Recurring Expenses

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

RecurringExpenseParamsGet #

Bases: LunchableModel

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

Parameters:

Name Type Description Default
start_date date
required
debit_as_negative bool | None
None
Source code in lunchable/models/recurring_expenses.py 
66
67
68
69
70
71
72
class RecurringExpenseParamsGet(LunchableModel):
    """
    https://lunchmoney.dev/#get-recurring-expenses
    """

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

RecurringExpensesClient #

Bases: LunchMoneyAPIClient

Lunch Money Recurring Expenses Interactions

Source code in lunchable/models/recurring_expenses.py 
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
class RecurringExpensesClient(LunchMoneyAPIClient):
    """
    Lunch Money Recurring Expenses Interactions
    """

    def get_recurring_expenses(
        self,
        start_date: Optional[datetime.date] = None,
        debit_as_negative: Optional[bool] = None,
    ) -> List[RecurringExpensesObject]:
        """
        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
        ----------
        start_date : Optional[datetime.date]
            Date to search. By default will return the first day of the current month
        debit_as_negative: bool
            Pass in true if you'd like expenses to be returned as negative amounts and credits as
            positive amounts.

        Returns
        -------
        List[RecurringExpensesObject]
        """
        if start_date is None:
            start_date = datetime.datetime.now().date().replace(day=1)
        params = RecurringExpenseParamsGet(
            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_EXPENSES],
            params=params,
        )
        recurring_expenses = response_data.get(APIConfig.LUNCH_MONEY_RECURRING_EXPENSES)
        recurring_expenses_objects = [
            RecurringExpensesObject.model_validate(item) for item in recurring_expenses
        ]
        logger.debug(
            "%s RecurringExpensesObjects retrieved", len(recurring_expenses_objects)
        )
        return recurring_expenses_objects

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]
Source code in lunchable/models/recurring_expenses.py 
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
def get_recurring_expenses(
    self,
    start_date: Optional[datetime.date] = None,
    debit_as_negative: Optional[bool] = None,
) -> List[RecurringExpensesObject]:
    """
    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
    ----------
    start_date : Optional[datetime.date]
        Date to search. By default will return the first day of the current month
    debit_as_negative: bool
        Pass in true if you'd like expenses to be returned as negative amounts and credits as
        positive amounts.

    Returns
    -------
    List[RecurringExpensesObject]
    """
    if start_date is None:
        start_date = datetime.datetime.now().date().replace(day=1)
    params = RecurringExpenseParamsGet(
        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_EXPENSES],
        params=params,
    )
    recurring_expenses = response_data.get(APIConfig.LUNCH_MONEY_RECURRING_EXPENSES)
    recurring_expenses_objects = [
        RecurringExpensesObject.model_validate(item) for item in recurring_expenses
    ]
    logger.debug(
        "%s RecurringExpensesObjects retrieved", len(recurring_expenses_objects)
    )
    return recurring_expenses_objects

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
transaction_id int | None

If any, denotes the unique identifier for the associated transaction matching this recurring expense for the current time period

 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 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
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
    )
    transaction_id: Optional[int] = Field(
        None, description=_RecurringExpensesDescriptions.transaction_id
    )
    category_id: Optional[int] = Field(
        None, description=_RecurringExpensesDescriptions.category_id
    )