@lunch-money/v2-api-spec 2.11.0-preview.3 → 2.11.0-preview.5

package/lunch-money-api-v2.yaml

@@ -1364,7 +1364,9 @@ components:
             - $ref: "#/components/schemas/accountTypeEnum"
         subtype:
           type: string
-          description: If set, an optional account subtype. Examples include<br>
+          nullable: true
+          description: If set, an optional account subtype. Set to `null` to clear it. 
+            Examples include<br>
             - retirement - checking - savings - prepaid credit card
           minLength: 1
           maxLength: 100
@@ -1791,7 +1793,10 @@ components:
               deleted: "#/components/schemas/balanceHistorySourceDeleted"
         balances:
           type: array
-          description: One or more monthly balance history entries for the source account.
+          description: >
+            Monthly balance history entries for the source account. On GET responses,
+            this includes all entries in the requested range. On PUT upsert responses,
+            this includes only the entries modified by that request.
           items:
             $ref: "#/components/schemas/balanceHistoryObject"
       required:
@@ -1816,7 +1821,7 @@ components:
         balance:
           type: string
           pattern: ^-?\d+(\.\d{1,4})?$
-          description: Historical balance stored for this entry. For manual and Plaid accounts this is in the account currency. For crypto accounts this is in the user's primary currency.
+          description: Historical balance stored for this entry, as a numeric string with up to four decimal places. Trailing zeros and decimal places are not guaranteed in responses. For manual and Plaid accounts this is in the account currency. For crypto accounts this is in the user's primary currency.
         currency:
           allOf:
             - $ref: "#/components/schemas/currencyEnum"
@@ -1863,7 +1868,7 @@ components:
         date:
           type: string
           format: date
-          description: Month to update, in YYYY-MM-DD format. This must be the first day of a month and must not be in the future.
+          description: Month to update, in YYYY-MM-DD format. This must be the first day of a month and must be in a past month.
         balance:
           oneOf:
             - type: number
@@ -1914,37 +1919,6 @@ components:
       required:
         - balances
 
-    balanceHistoryUpdateErrorObject:
-      type: object
-      x-internal: true
-      additionalProperties: true
-      properties:
-        request_balances_index:
-          type: integer
-          format: int32
-          description: Zero-based index into the `balances` request array
-        message:
-          type: string
-          description: Error message describing why the row could not be updated
-      required:
-        - request_balances_index
-        - message
-
-    upsertBalanceHistoryResponseObject:
-      type: object
-      x-internal: true
-      additionalProperties: false
-      properties:
-        updated_balance_history:
-          $ref: "#/components/schemas/balanceHistoryAccountObject"
-        errors:
-          type: array
-          items:
-            $ref: "#/components/schemas/balanceHistoryUpdateErrorObject"
-      required:
-        - updated_balance_history
-        - errors
-
     updateBalanceHistoryDetailsRequestObject:
       type: object
       x-internal: true
@@ -2483,14 +2457,9 @@ components:
         external_id:
           type: string
           nullable: true
-          description: A user-defined external ID for any transaction that was
-            added via csv import, `POST /transactions` API call, or manually
-            added via the Lunch Money app. No external ID exists for
-            transactions associated with synced accounts, and they cannot be
-            added. For transactions associated with manual accounts, the
-            external ID must be unique as attempts to add a subsequent
-            transaction with the same external_id and manual_account_id will be
-            flagged as duplicates and fail.
+          description: A user-defined external ID associated with the transaction. 
+            For transactions belonging to manual accounts, the
+            external ID must be unique for each transaction associated with the account.
           minLength: 0
           maxLength: 75
         tag_ids:
@@ -2887,14 +2856,9 @@ components:
         external_id:
           type: string
           nullable: true
-          description: A user-defined external ID for any transaction that was
-            added via csv import, `POST /transactions` API call, or manually
-            added via the Lunch Money app. No external ID exists for
-            transactions associated with synced accounts, and they cannot be
-            added. For transactions associated with manual accounts, the
-            external ID must be unique as attempts to add a subsequent
-            transaction with the same external_id and manual_account_id will be
-            flagged as duplicates and fail.
+          description: A user-defined external ID associated with the transaction. 
+            For transactions belonging to manual accounts, the
+            external ID must be unique for each transaction associated with the account.
           minLength: 0
           maxLength: 75
         plaid_metadata:
@@ -4013,7 +3977,9 @@ components:
             while processing the request.<br> If multiple errors were
             encountered, the list will contain multiple objects.<br> Each
             `error` object is guaranteed to have an `errMsg`, but it may also
-            contain other error specific properties.
+            contain other error-specific properties such as `code` (for example
+            `VALIDATION_ERROR`), or other properties that are useful to map
+             the error to the relevant part of the request.
           type: array
           items:
             type: object
@@ -5990,11 +5956,22 @@ paths:
               examples:
                 missing required properties:
                   value:
-                    message: Request Validation Failure
+                    message: Invalid Request Body
                     errors:
                       - errMsg: "Missing required property 'name' in request body."
                       - errMsg: "Missing required property 'balance' in request body."
                       - errMsg: "Missing required property 'symbol' in request body."
+                invalid balance:
+                  value:
+                    message: Invalid Request Body
+                    errors:
+                      - errMsg: "Invalid value for property 'balance'. 'abc' cannot be converted to a number"
+                      - errMsg: "Invalid value for property 'balance'. Invalid input"
+                invalid property:
+                  value:
+                    message: Invalid Request Body
+                    errors:
+                      - errMsg: "Invalid property 'coingecko_id' in request body."
                 unsupported symbol:
                   value:
                     message: Request Validation Failure
@@ -6742,7 +6719,7 @@ paths:
                   value:
                     message: Request Validation Failure
                     errors:
-                      - errMsg: "`start_date` must be less than or equal to `end_date`."
+                      - errMsg: "`start_date` must be before or equal to `end_date`."
                 not first of month:
                   value:
                     message: Request Validation Failure
@@ -6868,7 +6845,7 @@ paths:
                   value:
                     message: Request Validation Failure
                     errors:
-                      - errMsg: "`start_date` must be less than or equal to `end_date`."
+                      - errMsg: "`start_date` must be before or equal to `end_date`."
         "401":
           $ref: "#/components/responses/unauthorizedToken"
         "404":
@@ -6887,7 +6864,7 @@ paths:
                   value:
                     message: Not Found
                     errors:
-                      - errMsg: "There is no deleted balance history source with the id: 99999999."
+                      - errMsg: "Deleted balance history source 99999999 was not found."
         "429":
           $ref: "#/components/responses/rateLimited"
         "500":
@@ -6898,29 +6875,29 @@ paths:
       summary: Upsert balance history for an account
       description: >-
         Upsert one or more historical balance entries for a single manual, Plaid,
-        manual crypto, or deleted acount. Crypto synced accounts require an additional `symbol` path parameter.<br><br>
+        manual crypto, or deleted account. Crypto synced accounts require an additional `symbol` path parameter.<br><br>
 
-        The `account_type` path parameter identifies the the type of account and the
+        The `account_type` path parameter identifies the type of account and the
         `account_id` path parameter identifies the specific id for that account type.<br><br>
 
         Submit one or more entries in the `balances` array. Each entry must specify
         a `date` and `balance` value.<br><br>
 
         Balance history is monthly. Each entry's `date` must be the first day of
-        a month and must not be in the future.<br><br>
+        a month and must be in a past month.<br><br>
 
         `currency` may be provided for any balance entry. If omitted, it defaults
         to the account currency for manual/Plaid accounts, or the user's primary
         currency for crypto/deleted accounts.<br><br>
 
-        `symbol` is optional for `crypto_manual` accounts, tolerated for `deleted`
-        accounts, and invalid for `manual` or `plaid` accounts.<br><br>
+        `symbol` may only be set when `account_type` is `crypto_manual` or
+        `crypto_synced`. It is optional for `crypto_manual` accounts and tolerated
+        for `deleted` accounts.<br><br>
 
-        `crypto_balance` may be provided for `crypto_manual` and `deleted` accounts,
-        and is invalid for `manual` or `plaid` accounts.<br><br>
+        `crypto_balance` may be provided for `crypto_manual`, `crypto_synced`, and
+        `deleted` accounts, and is invalid for `manual` or `plaid` accounts.<br><br>
 
-        Use `PUT /v2/balance_history/deleted/{account_id}/details` to update
-        deleted-source metadata.
+        The response contains only the balance entries that were submitted in this request. 
       operationId: upsertBalanceHistoryForAccount
       parameters:
         - name: account_type
@@ -6965,7 +6942,7 @@ paths:
                       symbol: btc
                       crypto_balance: "0.020000000000000000"
                       currency: usd
-                      balance: "1255.0000"
+                      balance: "1255"
               get-shaped balance entry input:
                 value:
                   balances:
@@ -6975,60 +6952,71 @@ paths:
                       currency: usd
                       to_base: 41500
                       crypto_balance: null
-              partial success request:
-                value:
-                  balances:
-                    - date: "2026-03-01"
-                      balance: "41500.0000"
-                    - date: "2026-04-01"
-                      balance: "41625.5000"
-                      symbol: btc
       responses:
         "200":
-          description: One or more balance history entries were processed
+          description: Returns the modified balance entries only. Other historical
+            entries for the account are omitted from `balances`.
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/upsertBalanceHistoryResponseObject"
+                $ref: "#/components/schemas/balanceHistoryAccountObject"
               examples:
-                balances updated:
+                manual account bulk upsert:
+                  summary: Two upserted rows returned (not full account history)
                   value:
-                    updated_balance_history:
-                      source:
-                        type: manual
-                        manual_account_id: 119807
-                      balances:
-                        - id: 601
-                          date: "2026-03-01"
-                          balance: "41500.0000"
-                          currency: usd
-                          to_base: 41500
-                          crypto_balance: null
-                        - id: 602
-                          date: "2026-04-01"
-                          balance: "41625.5000"
-                          currency: usd
-                          to_base: 41625.5
-                          crypto_balance: null
-                    errors: []
-                partial success:
-                  value:
-                    updated_balance_history:
-                      source:
-                        type: manual
-                        manual_account_id: 119807
-                      balances:
-                        - id: 601
-                          date: "2026-03-01"
-                          balance: "41500.0000"
-                          currency: usd
-                          to_base: 41500
-                          crypto_balance: null
-                    errors:
-                      - request_balances_index: 1
-                        message: "`symbol` may not be set when `account_type` is `manual` or `plaid`."
+                    source:
+                      type: manual
+                      manual_account_id: 119807
+                    balances:
+                      - id: 601
+                        date: "2026-03-01"
+                        balance: "41500.0000"
+                        currency: usd
+                        to_base: 41500
+                        crypto_balance: null
+                      - id: 602
+                        date: "2026-04-01"
+                        balance: "41625.5000"
+                        currency: usd
+                        to_base: 41625.5
+                        crypto_balance: null
+                crypto manual balance with symbol:
+                  summary: Single upserted row returned
+                  value:
+                    source:
+                      type: crypto_manual
+                      crypto_manual_id: 22001
+                      symbol: btc
+                    balances:
+                      - id: 603
+                        date: "2026-03-01"
+                        balance: "56011.1200"
+                        currency: usd
+                        to_base: 56011.12
+                        crypto_balance: "0.852341920145782301"
+                deleted account bulk upsert:
+                  summary: Single upserted row returned
+                  value:
+                    source:
+                      type: deleted
+                      deleted_account_id: 91
+                      name: Savings
+                      institution_name: Old Bank
+                      display_name: Closed Savings
+                      account_type: savings
+                      subtype: savings
+                      mask: "1234"
+                      symbol: btc
+                    balances:
+                      - id: 504
+                        date: "2026-03-01"
+                        balance: "1255"
+                        currency: usd
+                        to_base: 1255
+                        crypto_balance: "0.020000000000000000"
         "400":
-          description: Bad Request
+          description: Bad Request. The entire request is rejected if any row in
+            `balances` fails validation; no rows are updated.
           content:
             application/json:
               schema:
@@ -7039,6 +7027,11 @@ paths:
                     message: Invalid Request Body
                     errors:
                       - errMsg: "Missing required property 'balances' in request body."
+                empty balances array:
+                  value:
+                    message: Invalid Request Body
+                    errors:
+                      - errMsg: "Invalid value for property 'balances'. Array must contain at least 1 element(s)"
                 invalid property:
                   value:
                     message: Invalid Request Body
@@ -7049,16 +7042,26 @@ paths:
                     message: Request Validation Failure
                     errors:
                       - errMsg: "`date` must be the first day of a month."
+                        request_balances_index: 0
+                        code: VALIDATION_ERROR
                 future date:
                   value:
                     message: Request Validation Failure
                     errors:
-                      - errMsg: "`date` must not be in the future."
+                      - errMsg: "`date` must be in a past month."
+                        request_balances_index: 1
                 crypto balance not allowed:
                   value:
                     message: Request Validation Failure
                     errors:
-                      - errMsg: "`crypto_balance` may only be set when `account_type` is `crypto_manual` or `deleted`."
+                      - errMsg: "`crypto_balance` may only be set when `account_type` is `crypto_manual`, `crypto_synced`, or `deleted`."
+                        request_balances_index: 0
+                invalid row in bulk request:
+                  value:
+                    message: Request Validation Failure
+                    errors:
+                      - errMsg: "`symbol` may only be set when `account_type` is `crypto_manual` or `crypto_synced`."
+                        request_balances_index: 1
         "401":
           $ref: "#/components/responses/unauthorizedToken"
         "404":
@@ -7201,7 +7204,7 @@ paths:
                   value:
                     message: Request Validation Failure
                     errors:
-                      - errMsg: "`start_date` must be less than or equal to `end_date`."
+                      - errMsg: "`start_date` must be before or equal to `end_date`."
         "401":
           $ref: "#/components/responses/unauthorizedToken"
         "404":
@@ -7220,7 +7223,7 @@ paths:
                   value:
                     message: Not Found
                     errors:
-                      - errMsg: "There is no synced crypto balance history stream for symbol 'doge' on account id: 33004."
+                      - errMsg: "There is no balance history for symbol 'doge' on this account."
         "429":
           $ref: "#/components/responses/rateLimited"
         "500":
@@ -7239,14 +7242,18 @@ paths:
         a `date` and `balance` value.<br><br>
 
         Balance history is monthly. Each entry's `date` must be the first day of
-        a month and must not be in the future.<br><br>
+        a month and must be in a past month.<br><br>
 
-        The request body must not include `symbol`; the symbol is supplied by the path.<br><br>
+        The request body may include an optional `symbol` on each balance entry. If
+        provided, it must match the `symbol` path parameter. Omit `symbol` to use
+        the path value.<br><br>
 
         `currency` may be provided for any balance entry. If omitted, it defaults
         to the user's primary currency for synced crypto balances.<br><br>
 
-        `crypto_balance` may be provided for synced crypto balances.
+        `crypto_balance` may be provided for synced crypto balances.<br><br>
+
+        The response contains only the balance entries that were submitted in this request. 
       operationId: upsertBalanceHistoryForCryptoSynced
       parameters:
         - name: account_id
@@ -7280,62 +7287,38 @@ paths:
                     - date: "2026-04-01"
                       balance: "6500.0000"
                       crypto_balance: "0.100020003000400050"
-              partial success request:
-                value:
-                  balances:
-                    - date: "2026-03-01"
-                      balance: "6400.0000"
-                      crypto_balance: "0.100020003000400050"
-                    - date: "2026-04-01"
-                      balance: "not-a-number"
       responses:
         "200":
-          description: One or more balance history entries were processed
+          description: Returns the modified balance entries only. Other historical
+            entries for the symbol stream are omitted from `balances`.
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/upsertBalanceHistoryResponseObject"
+                $ref: "#/components/schemas/balanceHistoryAccountObject"
               examples:
-                balances updated:
+                synced crypto bulk upsert:
+                  summary: Two upserted rows returned (not full symbol history)
                   value:
-                    updated_balance_history:
-                      source:
-                        type: crypto_synced
-                        crypto_synced_id: 33004
-                        symbol: btc
-                      balances:
-                        - id: 604
-                          date: "2026-03-01"
-                          balance: "6400.0000"
-                          currency: usd
-                          to_base: 6400
-                          crypto_balance: "0.100020003000400050"
-                        - id: 605
-                          date: "2026-04-01"
-                          balance: "6500.0000"
-                          currency: usd
-                          to_base: 6500
-                          crypto_balance: "0.100020003000400050"
-                    errors: []
-                partial success:
-                  value:
-                    updated_balance_history:
-                      source:
-                        type: crypto_synced
-                        crypto_synced_id: 33004
-                        symbol: btc
-                      balances:
-                        - id: 604
-                          date: "2026-03-01"
-                          balance: "6400.0000"
-                          currency: usd
-                          to_base: 6400
-                          crypto_balance: "0.100020003000400050"
-                    errors:
-                      - request_balances_index: 1
-                        message: "`balance` must be a valid numeric string or number."
+                    source:
+                      type: crypto_synced
+                      crypto_synced_id: 33004
+                      symbol: btc
+                    balances:
+                      - id: 604
+                        date: "2026-03-01"
+                        balance: "6400.0000"
+                        currency: usd
+                        to_base: 6400
+                        crypto_balance: "0.100020003000400050"
+                      - id: 605
+                        date: "2026-04-01"
+                        balance: "6500.0000"
+                        currency: usd
+                        to_base: 6500
+                        crypto_balance: "0.100020003000400050"
         "400":
-          description: Bad Request
+          description: Bad Request. The entire request is rejected if any row in
+            `balances` fails validation; no rows are updated.
           content:
             application/json:
               schema:
@@ -7346,16 +7329,35 @@ paths:
                     message: Invalid Request Body
                     errors:
                       - errMsg: "Missing required property 'balances' in request body."
+                empty balances array:
+                  value:
+                    message: Invalid Request Body
+                    errors:
+                      - errMsg: "Invalid value for property 'balances'. Array must contain at least 1 element(s)"
                 invalid date:
                   value:
                     message: Request Validation Failure
                     errors:
                       - errMsg: "`date` must be the first day of a month."
+                        request_balances_index: 0
                 future date:
                   value:
                     message: Request Validation Failure
                     errors:
-                      - errMsg: "`date` must not be in the future."
+                      - errMsg: "`date` must be in a past month."
+                        request_balances_index: 1
+                symbol mismatch:
+                  value:
+                    message: Request Validation Failure
+                    errors:
+                      - errMsg: "`symbol` in request body (doge) does not match the path symbol (eth)."
+                        request_balances_index: 0
+                invalid row in bulk request:
+                  value:
+                    message: Request Validation Failure
+                    errors:
+                      - errMsg: "`balance` must be a valid numeric string or number."
+                        request_balances_index: 1
         "401":
           $ref: "#/components/responses/unauthorizedToken"
         "404":
@@ -7374,7 +7376,7 @@ paths:
                   value:
                     message: Not Found
                     errors:
-                      - errMsg: "There is no synced crypto balance history stream for symbol 'doge' on account id: 33004."
+                      - errMsg: "There is no balance history for symbol 'doge' on this account."
         "429":
           $ref: "#/components/responses/rateLimited"
         "500":
@@ -7419,7 +7421,7 @@ paths:
               example:
                 message: Not Found
                 errors:
-                  - errMsg: "There is no synced crypto balance history stream for symbol 'doge' on account id: 33004."
+                  - errMsg: "There is no balance history for symbol 'doge' on this account."
         "429":
           $ref: "#/components/responses/rateLimited"
         "500":
@@ -7443,6 +7445,16 @@ paths:
       responses:
         "204":
           description: The balance history entry was deleted
+        "400":
+          description: Bad Request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/errorResponseObject"
+              example:
+                message: Request Validation Failure
+                errors:
+                  - errMsg: "Invalid value type for path parameter: 'id'. Expected 'number', received 'string'."
         "401":
           $ref: "#/components/responses/unauthorizedToken"
         "404":
@@ -7517,7 +7529,7 @@ paths:
               example:
                 message: Invalid Request Body
                 errors:
-                  - errMsg: "Request body must include at least one of: name, institution_name, display_name, account_type, subtype, mask."
+                  - errMsg: "At least one property must be provided: name, institution_name, display_name, account_type, subtype, mask."
         "401":
           $ref: "#/components/responses/unauthorizedToken"
         "404":
@@ -7529,7 +7541,7 @@ paths:
               example:
                 message: Not Found
                 errors:
-                  - errMsg: "There is no deleted balance history source with the id: 99999999."
+                  - errMsg: "Deleted balance history source 99999999 was not found."
         "429":
           $ref: "#/components/responses/rateLimited"
         "500":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunch-money/v2-api-spec",
-  "version": "2.11.0-preview.3",
+  "version": "2.11.0-preview.5",
   "description": "OpenAPI specification and version history for the Lunch Money v2 API",
   "main": "lunch-money-api-v2.yaml",
   "files": [

package/version-history.md

@@ -16,6 +16,7 @@ The Lunch Money API spec uses a modified version of SEMVER for its versioning me
 - Add `DELETE /balance_history/crypto_synced/{account_id}/{symbol}`
 - Add `PUT /balance_history/deleted/{account_id}/details`
 - Remove `rollover_pool` from the category object returned in the summary response. It is in the main summary response.
+- It is now possible to set an external_id on any transaction, including those that belong to a Plaid account.
 
 ## v2.10.0 - TBD
 - Add v2 crypto endpoints which support: