Skip to content

budgets#

Lunch Money - Budgets

https://lunchmoney.dev/#budget

BudgetConfigObject #

Bases: LunchableModel

Budget Configuration Object

Parameters:

Name Type Description Default
config_id int
required
cadence str
required
amount float | None
None
currency str | None
None
to_base float | None
None
auto_suggest str
required
Source code in lunchable/models/budgets.py 
33
34
35
36
37
38
39
40
41
42
43
class BudgetConfigObject(LunchableModel):
    """
    Budget Configuration Object
    """

    config_id: int
    cadence: str
    amount: Optional[float] = None
    currency: Optional[str] = None
    to_base: Optional[float] = None
    auto_suggest: str

BudgetDataObject #

Bases: LunchableModel

Data Object within a Budget

Parameters:

Name Type Description Default
budget_amount float | None
None
budget_currency str | None
None
budget_to_base float | None
None
spending_to_base float
0.0
num_transactions int
0
Source code in lunchable/models/budgets.py 
21
22
23
24
25
26
27
28
29
30
class BudgetDataObject(LunchableModel):
    """
    Data Object within a Budget
    """

    budget_amount: Optional[float] = None
    budget_currency: Optional[str] = None
    budget_to_base: Optional[float] = None
    spending_to_base: float = 0.00
    num_transactions: int = 0

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 
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
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
    )

BudgetParamsGet #

Bases: LunchableModel

https://lunchmoney.dev/#get-budget-summary

Parameters:

Name Type Description Default
start_date date
required
end_date date
required
Source code in lunchable/models/budgets.py 
81
82
83
84
85
86
87
class BudgetParamsGet(LunchableModel):
    """
    https://lunchmoney.dev/#get-budget-summary
    """

    start_date: datetime.date
    end_date: datetime.date

BudgetParamsPut #

Bases: LunchableModel

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

Parameters:

Name Type Description Default
start_date date
required
category_id int
required
amount float
required
currency str | None
None
Source code in lunchable/models/budgets.py 
90
91
92
93
94
95
96
97
98
class BudgetParamsPut(LunchableModel):
    """
    https://lunchmoney.dev/#upsert-budget
    """

    start_date: datetime.date
    category_id: int
    amount: float
    currency: Optional[str] = None

BudgetParamsRemove #

Bases: LunchableModel

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

Parameters:

Name Type Description Default
start_date date
required
category_id int
required
Source code in lunchable/models/budgets.py 
101
102
103
104
105
106
107
class BudgetParamsRemove(LunchableModel):
    """
    https://lunchmoney.dev/#remove-budget
    """

    start_date: datetime.date
    category_id: int

BudgetsClient #

Bases: LunchMoneyAPIClient

Lunch Money Budget Interactions

Source code in lunchable/models/budgets.py 
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
class BudgetsClient(LunchMoneyAPIClient):
    """
    Lunch Money Budget Interactions
    """

    def get_budgets(
        self, start_date: datetime.date, end_date: datetime.date
    ) -> List[BudgetObject]:
        """
        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
        -------
        List[BudgetObject]
        """
        params = BudgetParamsGet(start_date=start_date, end_date=end_date).model_dump()
        response_data = self.make_request(
            method=self.Methods.GET,
            url_path=[APIConfig.LUNCHMONEY_BUDGET],
            params=params,
        )
        budget_objects = [BudgetObject.model_validate(item) for item in response_data]
        return budget_objects

    def upsert_budget(
        self,
        start_date: datetime.date,
        category_id: int,
        amount: float,
        currency: Optional[str] = None,
    ) -> Optional[Dict[str, Any]]:
        """
        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
        ----------
        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)
        category_id: int
            Unique identifier for the category
        amount: float
            Amount for budget
        currency: Optional[str]
            Currency for the budgeted amount (optional). If empty, will default to your primary
            currency

        Returns
        -------
        Optional[Dict[str, Any]]
        """
        body = BudgetParamsPut(
            start_date=start_date,
            category_id=category_id,
            amount=amount,
            currency=currency,
        ).model_dump(exclude_none=True)
        response_data = self.make_request(
            method=self.Methods.PUT,
            url_path=[APIConfig.LUNCHMONEY_BUDGET],
            payload=body,
        )

        return response_data["category_group"]

    def remove_budget(self, start_date: datetime.date, category_id: int) -> bool:
        """
        Unset an Existing Budget for a Particular Category in a Particular Month

        Parameters
        ----------
        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)
        category_id: int
            Unique identifier for the category

        Returns
        -------
        bool
        """
        params = BudgetParamsRemove(
            start_date=start_date, category_id=category_id
        ).model_dump()
        response_data = self.make_request(
            method=self.Methods.DELETE,
            url_path=[APIConfig.LUNCHMONEY_BUDGET],
            params=params,
        )
        return response_data

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]
Source code in lunchable/models/budgets.py 
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
def get_budgets(
    self, start_date: datetime.date, end_date: datetime.date
) -> List[BudgetObject]:
    """
    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
    -------
    List[BudgetObject]
    """
    params = BudgetParamsGet(start_date=start_date, end_date=end_date).model_dump()
    response_data = self.make_request(
        method=self.Methods.GET,
        url_path=[APIConfig.LUNCHMONEY_BUDGET],
        params=params,
    )
    budget_objects = [BudgetObject.model_validate(item) for item in response_data]
    return budget_objects

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
Source code in lunchable/models/budgets.py 
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
def remove_budget(self, start_date: datetime.date, category_id: int) -> bool:
    """
    Unset an Existing Budget for a Particular Category in a Particular Month

    Parameters
    ----------
    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)
    category_id: int
        Unique identifier for the category

    Returns
    -------
    bool
    """
    params = BudgetParamsRemove(
        start_date=start_date, category_id=category_id
    ).model_dump()
    response_data = self.make_request(
        method=self.Methods.DELETE,
        url_path=[APIConfig.LUNCHMONEY_BUDGET],
        params=params,
    )
    return response_data

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]]
Source code in lunchable/models/budgets.py 
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
def upsert_budget(
    self,
    start_date: datetime.date,
    category_id: int,
    amount: float,
    currency: Optional[str] = None,
) -> Optional[Dict[str, Any]]:
    """
    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
    ----------
    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)
    category_id: int
        Unique identifier for the category
    amount: float
        Amount for budget
    currency: Optional[str]
        Currency for the budgeted amount (optional). If empty, will default to your primary
        currency

    Returns
    -------
    Optional[Dict[str, Any]]
    """
    body = BudgetParamsPut(
        start_date=start_date,
        category_id=category_id,
        amount=amount,
        currency=currency,
    ).model_dump(exclude_none=True)
    response_data = self.make_request(
        method=self.Methods.PUT,
        url_path=[APIConfig.LUNCHMONEY_BUDGET],
        payload=body,
    )

    return response_data["category_group"]