@lunch-money/developer-docs 2.11.2 → 2.11.3-preview.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,9 +1,8 @@
1
- **Beta Preview Portal** — This developer portal previews planned changes including:
2
- - Beta versions of new [v2 API](/v2/docs) endpoints:
3
- - [GET /me/account/settings](v2/docs#tag/me/GET/me/account/settings)
4
- - [PUT /me/account/settings](v2/docs#tag/me/PUT/me/account/settings)
5
- - [GET /me/user/settings](v2/docs#tag/me/GET/me/user/settings)
6
- - [PUT /me/user/settings](v2/docs#tag/me/PUT/me/user/settings)
1
+ **Beta Preview Portal** — This developer portal previews planned changes to [`GET /summary`](/v2/docs#tag/summary/GET/summary):
7
2
 
3
+ - Category objects now describe their rollover behavior with `rollover_option` and `rollover_start_date`.
4
+ - Totals for categories using same-category rollover now include `rollover_balance`.
5
+
6
+ These changes are available in the mock API for feedback, but are not yet available in the live API.
8
7
 
9
8
  Feedback is welcome. [Email dev-support@lunchmoney.app](mailto:dev-support@lunchmoney.app) or join us in the [developers channel](https://discord.com/channels/842337014556262411/1134594318414389258) on the [Lunch Money Discord](https://lunchmoney.app/discord).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lunch-money/developer-docs",
3
- "version": "2.11.2",
3
+ "version": "2.11.3-preview.2",
4
4
  "description": "Developer documentation content for Lunch Money APIs",
5
5
  "exports": {
6
6
  ".": "./package.json",
@@ -5,6 +5,11 @@ The Lunch Money API spec uses a modified version of SEMVER for its versioning me
5
5
  - The minor version represents the number of main endpoints the current version of the spec supports. For example, a version of the API that supports the /me, /categories, and /transactions endpoints would have a minor version of 3.
6
6
  - The revision number represents the number of updates since the last endpoint was added. For example, each time changes are made to one of the existing three APIs as described above, the revision number will be bumped.
7
7
 
8
+ ## v2.11.3 - TBD
9
+ - Add `rollover_option` and `rollover_start_date` to category objects in `GET /summary` responses.
10
+ - Add `rollover_balance` to category totals in aligned `GET /summary` responses for budgets that roll over within the same category.
11
+ - Rename the public rollover option value `available funds` to `general pool`.
12
+
8
13
  ## v2.11.2 - Nov 7, 2026
9
14
  - Allow `balance_as_of` to be `null` in manual account responses
10
15
 
@@ -27,7 +32,7 @@ The Lunch Money API spec uses a modified version of SEMVER for its versioning me
27
32
  - `DELETE /balance_history/{account_type}/{account_id}`
28
33
  - `DELETE /balance_history/crypto_synced/{account_id}/{symbol}`
29
34
  - `PUT /balance_history/deleted/{account_id}/details`
30
- - Remove `rollover_pool` from category objects in the `GET /summary` response
35
+ - Correct the `GET /summary` schema by removing `rollover_pool` from category objects. The server returned `rollover_pool` only at the top level.
31
36
  - Allow setting `external_id` on Plaid-account transactions
32
37
  - Allow `null` for `category_id` and `notes` on split children to clear those values instead of inheriting from the parent
33
38
 
@@ -4,7 +4,7 @@ info:
4
4
  description: |-
5
5
  ### Introduction
6
6
 
7
- Welcome to the Lunch Money v2 API reference. This is the **v2.11.2** spec.
7
+ Welcome to the Lunch Money v2 API reference. This is the **v2.11.3** spec.
8
8
 
9
9
  The API is available at `https://api.lunchmoney.dev/v2`. Get your access token from the [Lunch Money developers page](https://my.lunchmoney.app/developers).
10
10
 
@@ -42,7 +42,7 @@ info:
42
42
  license:
43
43
  name: Apache 2.0
44
44
  url: http://www.apache.org/licenses/LICENSE-2.0.html
45
- version: 2.11.2
45
+ version: 2.11.3
46
46
 
47
47
  servers:
48
48
  - url: https://api.lunchmoney.dev/v2
@@ -3612,11 +3612,11 @@ components:
3612
3612
  readOnly: true
3613
3613
  enum:
3614
3614
  - same category
3615
- - available funds
3615
+ - general pool
3616
3616
  description: "The rollover setting for this category. `same category`
3617
3617
  means unspent funds roll over to the next period for this category.
3618
- `available funds` means unspent funds are added to the available
3619
- funds pool. `null` means rollover is disabled."
3618
+ `general pool` means unspent funds are added to the general rollover
3619
+ pool. `null` means rollover is disabled."
3620
3620
  granularity:
3621
3621
  type: string
3622
3622
  readOnly: true
@@ -4414,6 +4414,19 @@ components:
4414
4414
  category_id:
4415
4415
  description: "ID of the category associated with the totals."
4416
4416
  type: integer
4417
+ rollover_option:
4418
+ type: string
4419
+ nullable: true
4420
+ enum:
4421
+ - same category
4422
+ - general pool
4423
+ description: >-
4424
+ The rollover setting that applies to this category's budget. `same category` means unspent funds roll over to the next period for this category. `general pool` means unspent funds are added to the general rollover pool instead, which is reported in the `rollover_pool` property of the response when `include_rollover_pool` is `true`. `null` means rollover is turned off for this budget.<p> This property is omitted for income categories, whose rollover is controlled by the account-level `budget_rollover_left_to_budget` setting from [GET /budgets/settings](#tag/budgets/GET/budgets/settings), and for category groups that are budgeted through their subcategories, where each subcategory has its own rollover setting. When a category group has its own budget, the rollover setting belongs to the group, and the group's value is also returned on its subcategories.<p> Rollover only counts budget periods on or after `rollover_start_date`, so `available` for earlier periods does not include rolled over funds.
4425
+ rollover_start_date:
4426
+ type: string
4427
+ format: date
4428
+ nullable: true
4429
+ description: The date from which rollover applies to this category in the given date range, in YYYY-MM-DD format. For a `same category` rollover this is the date of the most recent rollover reset on or before the start of the range; for a `general pool` rollover it is the date of the category's earliest rollover reset. Only budget periods on or after this date count towards `rollover_balance`. `null` if no rollover reset applies to the range, for example when the range starts before the first reset. This property is omitted when `rollover_option` is omitted or `null`. For a subcategory of a group with its own budget, this is the group's date.
4417
4430
  totals:
4418
4431
  $ref: "#/components/schemas/summaryCategoryTotalsObject"
4419
4432
  occurrences:
@@ -4497,6 +4510,10 @@ components:
4497
4510
  property will not be present in a non-aligned response."
4498
4511
  type: number
4499
4512
  nullable: true
4513
+ rollover_balance:
4514
+ type: number
4515
+ description: >-
4516
+ The rollover balance, in the user's default currency, that this category carries into the given date range. Only budget periods on or after `rollover_start_date` are counted. This is the funds carried forward from earlier budget periods, so `available` equals this value plus `budgeted` minus the category's activity in the range.<p> This property is present only when the category's `rollover_option` is `same category`, and it is not present in a non-aligned response. It is also not present for a subcategory of a group that has its own budget, because the group carries the rollover; use the group's value instead. For categories with a `general pool` rollover, see `rollover_pool` for the amount of funds in the pool (requires `include_rollover_pool=true`).
4500
4517
  recurring_remaining:
4501
4518
  description: "Total expected recurring activity, in the user's default
4502
4519
  currency, that has not yet occurred for the category within the
@@ -5423,7 +5440,7 @@ paths:
5423
5440
  "aligned monthly":
5424
5441
  summary: "End date for monthly budget period"
5425
5442
  description: "Last day of month for aligned budget periods"
5426
- value: "2025-08-31"
5443
+ value: "2025-07-31"
5427
5444
  "not aligned":
5428
5445
  summary: "End date for non-aligned period"
5429
5446
  description: "Date that doesn't align with budget periods"
@@ -5485,18 +5502,19 @@ paths:
5485
5502
  examples:
5486
5503
  "aligned monthly":
5487
5504
  summary: "Monthly budget summary aligned with budget periods"
5488
- description: "Example response for a date range that aligns
5489
- with monthly budget periods (1st to last day of month) with
5490
- occurrences included"
5505
+ description: "Single-period aligned response showing category 315177 with same-category rollover, 315628 with general-pool rollover, 86 with rollover off, income category 88, group-budget category 400001, and its subcategory 400002."
5491
5506
  value:
5492
5507
  aligned: true
5493
5508
  categories:
5494
5509
  - category_id: 315177
5510
+ rollover_option: same category
5511
+ rollover_start_date: "2025-01-01"
5495
5512
  totals:
5496
5513
  other_activity: 156.64
5497
5514
  recurring_activity: 0
5498
5515
  budgeted: 500
5499
- available: 343.36
5516
+ available: 418.36
5517
+ rollover_balance: 75
5500
5518
  recurring_remaining: 0
5501
5519
  recurring_expected: 0
5502
5520
  occurrences:
@@ -5509,16 +5527,9 @@ paths:
5509
5527
  budgeted_amount: "500.0000"
5510
5528
  budgeted_currency: "usd"
5511
5529
  notes: "Monthly budget allocation"
5512
- - in_range: true
5513
- start_date: "2025-08-01"
5514
- end_date: "2025-08-31"
5515
- other_activity: 0
5516
- recurring_activity: 0
5517
- budgeted: 500
5518
- budgeted_amount: "500.0000"
5519
- budgeted_currency: "usd"
5520
- notes: "Adjusted for seasonal spending"
5521
5530
  - category_id: 315628
5531
+ rollover_option: general pool
5532
+ rollover_start_date: "2025-01-01"
5522
5533
  totals:
5523
5534
  other_activity: 424.8
5524
5535
  recurring_activity: 0
@@ -5536,16 +5547,8 @@ paths:
5536
5547
  budgeted_amount: "200.0000"
5537
5548
  budgeted_currency: "usd"
5538
5549
  notes: "Based on previous month's activity"
5539
- - in_range: true
5540
- start_date: "2025-08-01"
5541
- end_date: "2025-08-31"
5542
- other_activity: 0
5543
- recurring_activity: 0
5544
- budgeted: 200
5545
- budgeted_amount: "200.0000"
5546
- budgeted_currency: "usd"
5547
- notes: "Emergency fund contribution"
5548
5550
  - category_id: 86
5551
+ rollover_option: null
5549
5552
  totals:
5550
5553
  other_activity: 25.69
5551
5554
  recurring_activity: 0
@@ -5563,15 +5566,35 @@ paths:
5563
5566
  budgeted_amount: "200.0000"
5564
5567
  budgeted_currency: "usd"
5565
5568
  notes: "Holiday spending budget"
5566
- - in_range: true
5567
- start_date: "2025-08-01"
5568
- end_date: "2025-08-31"
5569
- other_activity: 0
5570
- recurring_activity: 0
5571
- budgeted: 200
5572
- budgeted_amount: "200.0000"
5573
- budgeted_currency: "usd"
5574
- notes: "Summer vacation savings"
5569
+ - category_id: 88
5570
+ totals:
5571
+ other_activity: -2501.68
5572
+ recurring_activity: 0
5573
+ budgeted: null
5574
+ available: null
5575
+ recurring_remaining: 0
5576
+ recurring_expected: -2501.68
5577
+ - category_id: 400001
5578
+ rollover_option: same category
5579
+ rollover_start_date: "2025-04-01"
5580
+ totals:
5581
+ other_activity: 300
5582
+ recurring_activity: 0
5583
+ budgeted: 600
5584
+ available: 350
5585
+ rollover_balance: 50
5586
+ recurring_remaining: 0
5587
+ recurring_expected: 0
5588
+ - category_id: 400002
5589
+ rollover_option: same category
5590
+ rollover_start_date: "2025-04-01"
5591
+ totals:
5592
+ other_activity: 120
5593
+ recurring_activity: 0
5594
+ budgeted: null
5595
+ available: null
5596
+ recurring_remaining: 0
5597
+ recurring_expected: 0
5575
5598
  "not aligned":
5576
5599
  summary: "Budget summary for non-aligned date range"
5577
5600
  description: "Example response for a date range that does not
@@ -5580,59 +5603,55 @@ paths:
5580
5603
  aligned: false
5581
5604
  categories:
5582
5605
  - category_id: 315177
5606
+ rollover_option: same category
5607
+ rollover_start_date: "2025-01-01"
5583
5608
  totals:
5584
5609
  other_activity: 156.64
5585
5610
  recurring_activity: 0
5586
- budgeted: 400
5587
- available: 243.36
5588
5611
  recurring_remaining: 0
5589
5612
  recurring_expected: 0
5590
5613
  - category_id: 315628
5614
+ rollover_option: general pool
5615
+ rollover_start_date: "2025-01-01"
5591
5616
  totals:
5592
5617
  other_activity: 424.8
5593
5618
  recurring_activity: 0
5594
- budgeted: null
5595
- available: null
5596
5619
  recurring_remaining: 0
5597
5620
  recurring_expected: 0
5598
5621
  - category_id: 78
5622
+ rollover_option: null
5599
5623
  totals:
5600
5624
  other_activity: 0
5601
5625
  recurring_activity: 0
5602
- budgeted: null
5603
- available: null
5604
5626
  recurring_remaining: 0
5605
5627
  recurring_expected: 0
5606
5628
  - category_id: 83
5629
+ rollover_option: same category
5630
+ rollover_start_date: null
5607
5631
  totals:
5608
5632
  other_activity: 0
5609
5633
  recurring_activity: 0
5610
- budgeted: null
5611
- available: null
5612
5634
  recurring_remaining: 1700
5613
5635
  recurring_expected: 1700
5614
5636
  - category_id: 88
5615
5637
  totals:
5616
5638
  other_activity: 0
5617
5639
  recurring_activity: 2501.68
5618
- budgeted: null
5619
- available: null
5620
5640
  recurring_remaining: 0
5621
5641
  recurring_expected: 2501.68
5622
5642
  - category_id: 86
5643
+ rollover_option: null
5623
5644
  totals:
5624
5645
  other_activity: 25.69
5625
5646
  recurring_activity: 0
5626
- budgeted: 200
5627
- available: 174.31
5628
5647
  recurring_remaining: 0
5629
5648
  recurring_expected: 0
5630
5649
  - category_id: 84
5650
+ rollover_option: same category
5651
+ rollover_start_date: "2025-01-01"
5631
5652
  totals:
5632
5653
  other_activity: 401.12
5633
5654
  recurring_activity: 4.13
5634
- budgeted: 150
5635
- available: -255.25
5636
5655
  recurring_remaining: -4.13
5637
5656
  recurring_expected: 0
5638
5657
  "summarized totals":
@@ -5644,11 +5663,14 @@ paths:
5644
5663
  aligned: true
5645
5664
  categories:
5646
5665
  - category_id: 315177
5666
+ rollover_option: same category
5667
+ rollover_start_date: "2025-01-01"
5647
5668
  totals:
5648
5669
  other_activity: 156.64
5649
5670
  recurring_activity: 0
5650
5671
  budgeted: 400
5651
- available: 243.36
5672
+ available: 283.36
5673
+ rollover_balance: 40
5652
5674
  recurring_remaining: 0
5653
5675
  recurring_expected: 0
5654
5676
  occurrences:
@@ -5662,6 +5684,8 @@ paths:
5662
5684
  budgeted_currency: "usd"
5663
5685
  notes: "Monthly budget allocation"
5664
5686
  - category_id: 315628
5687
+ rollover_option: general pool
5688
+ rollover_start_date: "2025-01-01"
5665
5689
  totals:
5666
5690
  other_activity: 424.8
5667
5691
  recurring_activity: 0
@@ -5680,6 +5704,7 @@ paths:
5680
5704
  budgeted_currency: "usd"
5681
5705
  notes: "Based on previous month's activity"
5682
5706
  - category_id: 315629
5707
+ rollover_option: null
5683
5708
  totals:
5684
5709
  other_activity: 0
5685
5710
  recurring_activity: 0
@@ -5712,18 +5737,19 @@ paths:
5712
5737
  uncategorized_recurring: 0
5713
5738
  "with occurrences":
5714
5739
  summary: "Monthly budget summary with occurrences included"
5715
- description: "Example response for aligned monthly budget
5716
- periods with occurrences showing individual budget period
5717
- details for each category"
5740
+ description: "Example response for one aligned monthly budget period with occurrences showing individual budget period details for each category"
5718
5741
  value:
5719
5742
  aligned: true
5720
5743
  categories:
5721
5744
  - category_id: 315177
5745
+ rollover_option: same category
5746
+ rollover_start_date: "2025-01-01"
5722
5747
  totals:
5723
5748
  other_activity: 156.64
5724
5749
  recurring_activity: 0
5725
5750
  budgeted: 500
5726
- available: 343.36
5751
+ available: 418.36
5752
+ rollover_balance: 75
5727
5753
  recurring_remaining: 0
5728
5754
  recurring_expected: 0
5729
5755
  occurrences:
@@ -5736,16 +5762,9 @@ paths:
5736
5762
  budgeted_amount: "500.0000"
5737
5763
  budgeted_currency: "usd"
5738
5764
  notes: "Monthly budget allocation"
5739
- - in_range: true
5740
- start_date: "2025-08-01"
5741
- end_date: "2025-08-31"
5742
- other_activity: 0
5743
- recurring_activity: 0
5744
- budgeted: 500
5745
- budgeted_amount: "500.0000"
5746
- budgeted_currency: "usd"
5747
- notes: "Adjusted for seasonal spending"
5748
5765
  - category_id: 315628
5766
+ rollover_option: general pool
5767
+ rollover_start_date: "2025-01-01"
5749
5768
  totals:
5750
5769
  other_activity: 424.8
5751
5770
  recurring_activity: 0
@@ -5763,16 +5782,8 @@ paths:
5763
5782
  budgeted_amount: "200.0000"
5764
5783
  budgeted_currency: "usd"
5765
5784
  notes: "Based on previous month's activity"
5766
- - in_range: true
5767
- start_date: "2025-08-01"
5768
- end_date: "2025-08-31"
5769
- other_activity: 0
5770
- recurring_activity: 0
5771
- budgeted: 200
5772
- budgeted_amount: "200.0000"
5773
- budgeted_currency: "usd"
5774
- notes: "Emergency fund contribution"
5775
5785
  - category_id: 86
5786
+ rollover_option: null
5776
5787
  totals:
5777
5788
  other_activity: 25.69
5778
5789
  recurring_activity: 0
@@ -5790,15 +5801,6 @@ paths:
5790
5801
  budgeted_amount: "200.0000"
5791
5802
  budgeted_currency: "usd"
5792
5803
  notes: "Holiday spending budget"
5793
- - in_range: true
5794
- start_date: "2025-08-01"
5795
- end_date: "2025-08-31"
5796
- other_activity: 0
5797
- recurring_activity: 0
5798
- budgeted: 200
5799
- budgeted_amount: "200.0000"
5800
- budgeted_currency: "usd"
5801
- notes: "Summer vacation savings"
5802
5804
  "with past occurrences":
5803
5805
  summary: "Monthly budget summary with past occurrences included"
5804
5806
  description: "Example response for aligned monthly budget
@@ -5808,11 +5810,14 @@ paths:
5808
5810
  aligned: true
5809
5811
  categories:
5810
5812
  - category_id: 315177
5813
+ rollover_option: same category
5814
+ rollover_start_date: "2025-01-01"
5811
5815
  totals:
5812
5816
  other_activity: 156.64
5813
5817
  recurring_activity: 0
5814
5818
  budgeted: 500
5815
- available: 343.36
5819
+ available: 418.36
5820
+ rollover_balance: 75
5816
5821
  recurring_remaining: 0
5817
5822
  recurring_expected: 0
5818
5823
  occurrences:
@@ -5879,6 +5884,8 @@ paths:
5879
5884
  to_base: 80.00
5880
5885
  categories:
5881
5886
  - category_id: 315177
5887
+ rollover_option: general pool
5888
+ rollover_start_date: "2025-01-01"
5882
5889
  totals:
5883
5890
  other_activity: 156.64
5884
5891
  recurring_activity: 0