@lunch-money/v2-api-spec 2.11.1-preview.5 → 2.11.1-preview.8

package/lunch-money-api-v2.yaml

@@ -53,9 +53,11 @@ servers:
 tags:
   - name: me
     description: View details and settings for the current user and account.<p>
-      Use [/me/account/settings](#tag/me/GET/me/account/settings) and
-      [/me/user/settings](#tag/me/GET/me/user/settings) for account- and
-      user-level preferences.
+      Use [/me/user/settings](#tag/me/GET/me/user/settings) for user-wide
+      preferences, [/me/account/settings](#tag/me/GET/me/account/settings) for
+      account-wide preferences, and
+      [/me/user/account/settings](#tag/me/GET/me/user/account/settings) for
+      preferences specific to the current user and budgeting account.
   - name: categories
     description: Work with categories
     externalDocs:
@@ -3798,6 +3800,7 @@ components:
         - budget_rollover_left_to_budget
 
     weekStartsOnEnum:
+      x-internal: true
       type: string
       title: week starts on enum
       enum:
@@ -3806,6 +3809,7 @@ components:
       description: The day on which a calendar week begins.
 
     monthYearFormatEnum:
+      x-internal: true
       type: string
       title: month and year format enum
       description: Format string for displaying month and year values
@@ -3832,6 +3836,7 @@ components:
         - "YYYY/MM"
 
     monthDayYearFormatEnum:
+      x-internal: true
       type: string
       title: month, day and year format enum
       description: Format string for displaying full dates in the
@@ -3889,6 +3894,7 @@ components:
         - "M/DD/YYYY"
 
     monthDayFormatEnum:
+      x-internal: true
       type: string
       title: month and day format enum
       description: Format string for displaying month and day values
@@ -3931,6 +3937,98 @@ components:
         - "DD.M"
         - "DD/M"
 
+    localeEnum:
+      type: string
+      title: locale enum
+      description: Locale used for formatting numbers and currency amounts in
+        the Lunch Money app.
+      example: en-US
+      enum:
+        - sq-AL # Albanian (Albania)
+        - be-BY # Belarusian (Belarus)
+        - bg-BG # Bulgarian (Bulgaria)
+        - ca-ES # Catalan (Spain)
+        - zh-CN # Chinese (Simplified) (China)
+        - zh-HK # Chinese (Traditional) (Hong Kong)
+        - zh-TW # Chinese (Traditional) (Taiwan)
+        - hr-HR # Croatian (Croatia)
+        - cs-CZ # Czech (Czech Republic)
+        - da-DK # Danish (Denmark)
+        - nl-BE # Dutch (Belgium)
+        - nl-NL # Dutch (Netherlands)
+        - en-AU # English (Australia)
+        - en-CA # English (Canada)
+        - en-IN # English (India)
+        - en-IE # English (Ireland)
+        - en-MT # English (Malta)
+        - en-NZ # English (New Zealand)
+        - en-PH # English (Philippines)
+        - en-SG # English (Singapore)
+        - en-ZA # English (South Africa)
+        - en-GB # English (United Kingdom)
+        - en-US # English (United States)
+        - et-EE # Estonian (Estonia)
+        - fi-FI # Finnish (Finland)
+        - fr-BE # French (Belgium)
+        - fr-CA # French (Canada)
+        - fr-FR # French (France)
+        - fr-LU # French (Luxembourg)
+        - fr-CH # French (Switzerland)
+        - de-AT # German (Austria)
+        - de-DE # German (Germany)
+        - de-LU # German (Luxembourg)
+        - de-CH # German (Switzerland)
+        - el-CY # Greek (Cyprus)
+        - el-GR # Greek (Greece)
+        - iw-IL # Hebrew (Israel); modern replacement: he-IL
+        - hi-IN # Hindi (India)
+        - hu-HU # Hungarian (Hungary)
+        - is-IS # Icelandic (Iceland)
+        - in-ID # Indonesian (Indonesia); modern replacement: id-ID
+        - ga-IE # Irish (Ireland)
+        - it-IT # Italian (Italy)
+        - it-CH # Italian (Switzerland)
+        - ja-JP # Japanese (Japan)
+        - ko-KR # Korean (South Korea)
+        - lv-LV # Latvian (Latvia)
+        - lt-LT # Lithuanian (Lithuania)
+        - mk-MK # Macedonian (Macedonia)
+        - ms-MY # Malay (Malaysia)
+        - mt-MT # Maltese (Malta)
+        - no-NO # Norwegian (Norway)
+        - pl-PL # Polish (Poland)
+        - pt-BR # Portuguese (Brazil)
+        - pt-PT # Portuguese (Portugal)
+        - ro-RO # Romanian (Romania)
+        - ru-RU # Russian (Russia)
+        - sk-SK # Slovak (Slovakia)
+        - sl-SI # Slovenian (Slovenia)
+        - es-AR # Spanish (Argentina)
+        - es-BO # Spanish (Bolivia)
+        - es-CL # Spanish (Chile)
+        - es-CO # Spanish (Colombia)
+        - es-CR # Spanish (Costa Rica)
+        - es-DO # Spanish (Dominican Republic)
+        - es-EC # Spanish (Ecuador)
+        - es-SV # Spanish (El Salvador)
+        - es-GT # Spanish (Guatemala)
+        - es-HN # Spanish (Honduras)
+        - es-MX # Spanish (Mexico)
+        - es-NI # Spanish (Nicaragua)
+        - es-PA # Spanish (Panama)
+        - es-PY # Spanish (Paraguay)
+        - es-PE # Spanish (Peru)
+        - es-PR # Spanish (Puerto Rico)
+        - es-ES # Spanish (Spain)
+        - es-US # Spanish (United States)
+        - es-UY # Spanish (Uruguay)
+        - es-VE # Spanish (Venezuela)
+        - sv-SE # Swedish (Sweden)
+        - th-TH # Thai (Thailand)
+        - tr-TR # Turkish (Turkey)
+        - uk-UA # Ukrainian (Ukraine)
+        - vi-VN # Vietnamese (Vietnam)
+
     accountSettingsObject:
       type: object
       title: account settings object
@@ -3954,13 +4052,19 @@ components:
           description: Display name of the budgeting account in the Lunch Money
             app.
         locale:
-          type: string
-          description: Locale used for formatting dates and numbers in the
-            Lunch Money app (for example, `en-US`). When no locale is explicitly
-            stored for the account, the effective locale is derived from the
-            `default_locale` associated with `primary_currency` in the
-            currencies table (for example, `usd` → `en-US`, `cad` → `en-CA`,
-            `gbp` → `en-GB`).
+          allOf:
+            - $ref: "#/components/schemas/localeEnum"
+          example: en-US
+          description: Locale used for formatting numbers and currency amounts
+            in the Lunch Money app (for example, `en-US`). See
+            [Supported Locales](https://lunchmoney.dev/v2/locales) for accepted
+            values. Date presentation is configured separately through
+            [GET /me/user/settings](#tag/me/GET/me/user/settings) and
+            [PUT /me/user/settings](#tag/me/PUT/me/user/settings). When no
+            locale is explicitly stored for the account, the effective locale
+            is derived from the `default_locale` associated with
+            `primary_currency` in the currencies table (for example, `usd` →
+            `en-US`, `cad` → `en-CA`, `gbp` → `en-GB`).
         auto_create_category_rules:
           type: boolean
           default: true
@@ -3971,16 +4075,11 @@ components:
           default: true
           description: If `true`, suggested transaction rules are created
             automatically.
-        auto_review_transaction_on_update:
+        include_pending_in_totals:
           type: boolean
           default: true
-          description: If `true`, transactions are marked as reviewed when
-            updated.
-        auto_review_transaction_on_creation:
-          type: boolean
-          default: true
-          description: If `true`, transactions are marked as reviewed when
-            created.
+          description: If `true`, pending transactions are included in account
+            totals.
       required:
         - primary_currency
         - supported_currencies
@@ -3988,13 +4087,13 @@ components:
         - locale
         - auto_create_category_rules
         - auto_create_suggested_transaction_rules
-        - auto_review_transaction_on_update
-        - auto_review_transaction_on_creation
+        - include_pending_in_totals
 
     updateAccountSettingsRequestObject:
       x-internal: true
       type: object
       additionalProperties: false
+      minProperties: 1
       description: Request body for updating account settings. Include at least
         one property to update.
       properties:
@@ -4016,9 +4115,15 @@ components:
           description: If set, updates the display name of the budgeting account.
           x-updatable: true
         locale:
-          type: string
-          description: If set, updates the locale used for formatting dates and
-            numbers in the Lunch Money app.
+          allOf:
+            - $ref: "#/components/schemas/localeEnum"
+          example: en-US
+          description: If set, updates the locale used for formatting numbers
+            and currency amounts in the Lunch Money app. See
+            [Supported Locales](https://lunchmoney.dev/v2/locales) for accepted
+            values. Date presentation is configured separately through
+            [GET /me/user/settings](#tag/me/GET/me/user/settings) and
+            [PUT /me/user/settings](#tag/me/PUT/me/user/settings).
           x-updatable: true
         auto_create_category_rules:
           type: boolean
@@ -4030,15 +4135,70 @@ components:
           description: If set, updates whether suggested transaction rules are
             created automatically.
           x-updatable: true
+        include_pending_in_totals:
+          type: boolean
+          description: If set, updates whether pending transactions are included
+            in account totals.
+          x-updatable: true
+
+    userAccountSettingsObject:
+      type: object
+      title: user account settings object
+      additionalProperties: false
+      description: Settings specific to the authorized user within the current
+        budgeting account.
+      properties:
+        auto_review_transaction_on_update:
+          type: boolean
+          default: true
+          description: If `true`, transactions are marked as reviewed when their
+            date, category, payee, amount, account, or notes are changed.
+        auto_review_transaction_on_creation:
+          type: boolean
+          default: true
+          description: If `true`, new manual transactions start as reviewed. If
+            `false`, they start as unreviewed.
+        default_manual_account_id:
+          type: integer
+          nullable: true
+          description: Manual account selected by default when the user creates a
+            manual transaction in the current budgeting account. Must identify a
+            manual account returned by
+            [GET /manual_accounts](#tag/manual_accounts/GET/manual_accounts) for
+            the current budgeting account. Set to `null` to clear the selection.
+      required:
+        - auto_review_transaction_on_update
+        - auto_review_transaction_on_creation
+        - default_manual_account_id
+
+    updateUserAccountSettingsRequestObject:
+      x-internal: true
+      type: object
+      additionalProperties: false
+      minProperties: 1
+      description: Request body for updating settings specific to the authorized
+        user within the current budgeting account. Include at least one property
+        to update.
+      properties:
         auto_review_transaction_on_update:
           type: boolean
           description: If set, updates whether transactions are marked as reviewed
-            when updated.
+            when their date, category, payee, amount, account, or notes are
+            changed.
           x-updatable: true
         auto_review_transaction_on_creation:
           type: boolean
-          description: If set, updates whether transactions are marked as reviewed
-            when created.
+          description: If set, updates whether new manual transactions start as
+            reviewed or unreviewed.
+          x-updatable: true
+        default_manual_account_id:
+          type: integer
+          nullable: true
+          description: If set, updates the manual account selected by default when
+            the user creates a manual transaction in the current budgeting
+            account. Must identify a manual account returned by
+            [GET /manual_accounts](#tag/manual_accounts/GET/manual_accounts) for
+            the current budgeting account. Set to `null` to clear the selection.
           x-updatable: true
 
     userSettingsObject:
@@ -4114,6 +4274,7 @@ components:
       x-internal: true
       type: object
       additionalProperties: false
+      minProperties: 1
       description: Request body for updating user settings. Include at least one
         property to update.
       properties:
@@ -4950,11 +5111,14 @@ paths:
       summary: Get current user
       description: |-
         Get details about the user associated with the supplied authorization
-        token.<p> For account- and user-level preferences, prefer
-        [/me/account/settings](#tag/me/GET/me/account/settings) and
-        [/me/user/settings](#tag/me/GET/me/user/settings). Properties such as
-        `primary_currency` and `budget_name` remain on this response for
-        backwards compatibility.
+        token.<p> Use [/me/user/settings](#tag/me/GET/me/user/settings) for
+        user-wide preferences,
+        [/me/account/settings](#tag/me/GET/me/account/settings) for account-wide
+        preferences, and
+        [/me/user/account/settings](#tag/me/GET/me/user/account/settings) for
+        preferences specific to the current user and budgeting account.
+        Properties such as `primary_currency` and `budget_name` remain on this
+        response for backwards compatibility.
       operationId: getMe
       parameters: []
       responses:
@@ -4983,8 +5147,9 @@ paths:
       tags:
         - me
       summary: Get account settings
-      description: |-
-        Returns account-level settings for the budgeting account associated with the authorized API token.
+      description: >-
+        Returns settings for the current budgeting account. These settings apply
+        regardless of which user is accessing the account.
       operationId: getAccountSettings
       responses:
         "200":
@@ -5003,8 +5168,7 @@ paths:
                 locale: en-US
                 auto_create_category_rules: true
                 auto_create_suggested_transaction_rules: true
-                auto_review_transaction_on_update: true
-                auto_review_transaction_on_creation: true
+                include_pending_in_totals: true
         "401":
           $ref: "#/components/responses/unauthorizedToken"
         "429":
@@ -5017,11 +5181,10 @@ paths:
       summary: Update account settings
       description: |-
         Updates account-level settings for the budgeting account
-        associated with the authorized API token.<p> You may submit the response from a
-        `GET /me/account/settings` as the request body; however, only certain
-        properties can be updated.<p> It is also possible to provide only the
-        properties to be updated in the request body, as long as the request
-        includes at least one updatable property.
+        associated with the authorized API token. Submit the full response from
+        `GET /me/account/settings` with one or more properties changed, or
+        provide only the properties to update. The request body must include at
+        least one property.
       operationId: updateAccountSettings
       requestBody:
         required: true
@@ -5036,7 +5199,7 @@ paths:
               Update automation preferences:
                 value:
                   auto_create_category_rules: false
-                  auto_review_transaction_on_creation: false
+                  include_pending_in_totals: false
       responses:
         "200":
           description: Account settings updated successfully
@@ -5061,8 +5224,10 @@ paths:
       tags:
         - me
       summary: Get user settings
-      description: |-
-        Returns user-level display and formatting preferences for the user associated with the authorized API token.
+      description: >-
+        Returns display and formatting preferences for the authorized user.
+        These settings apply across every budgeting account the user owns or
+        collaborates on.
       operationId: getUserSettings
       responses:
         "200":
@@ -5093,11 +5258,10 @@ paths:
       summary: Update user settings
       description: |-
         Updates user-level display and formatting preferences for the user
-        associated with the authorized API token.<p> You may submit the response
-        from a `GET /me/user/settings` as the request body; however, only
-        certain properties can be updated.<p> It is also possible to provide
-        only the properties to be updated in the request body, as long as the
-        request includes at least one updatable property.<p> Updating
+        associated with the authorized API token. Submit the full response from
+        `GET /me/user/settings` with one or more properties changed, or provide
+        only the properties to update. The request body must include at least
+        one property.<p> Updating
         `show_debits_as_negative` affects display in the Lunch Money app only.
         Amount fields in API responses always use positive values for debits and
         negative values for credits.
@@ -5137,6 +5301,88 @@ paths:
           $ref: "#/components/responses/rateLimited"
         "500":
           $ref: "#/components/responses/serverError"
+  /me/user/account/settings:
+    get:
+      tags:
+        - me
+      summary: Get user account settings
+      description: >-
+        Returns settings specific to the authorized user within the current
+        budgeting account. These settings do not affect other users or the
+        authorized user's settings in other budgeting accounts.
+      operationId: getUserAccountSettings
+      responses:
+        "200":
+          description: Settings for the authorized user in the current budgeting
+            account
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/userAccountSettingsObject"
+              example:
+                auto_review_transaction_on_update: true
+                auto_review_transaction_on_creation: true
+                default_manual_account_id: null
+        "401":
+          $ref: "#/components/responses/unauthorizedToken"
+        "429":
+          $ref: "#/components/responses/rateLimited"
+        "500":
+          $ref: "#/components/responses/serverError"
+    put:
+      tags:
+        - me
+      summary: Update user account settings
+      description: |-
+        Updates settings specific to the authorized user within the current
+        budgeting account. Submit the full response from
+        `GET /me/user/account/settings` with one or more properties changed, or
+        provide only the properties to update. The request body must include at
+        least one property.
+      operationId: updateUserAccountSettings
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/updateUserAccountSettingsRequestObject"
+            examples:
+              Update review preference:
+                value:
+                  auto_review_transaction_on_creation: false
+              Clear default manual account:
+                value:
+                  default_manual_account_id: null
+      responses:
+        "200":
+          description: User account settings updated successfully
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/userAccountSettingsObject"
+              examples:
+                Update review preference:
+                  value:
+                    auto_review_transaction_on_update: true
+                    auto_review_transaction_on_creation: false
+                    default_manual_account_id: null
+                Clear default manual account:
+                  value:
+                    auto_review_transaction_on_update: true
+                    auto_review_transaction_on_creation: true
+                    default_manual_account_id: null
+        "400":
+          description: Invalid request body
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/errorResponseObject"
+        "401":
+          $ref: "#/components/responses/unauthorizedToken"
+        "429":
+          $ref: "#/components/responses/rateLimited"
+        "500":
+          $ref: "#/components/responses/serverError"
   /summary:
     get:
       tags:

package/package.json

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

package/version-history.md

@@ -8,6 +8,10 @@ The Lunch Money API spec uses a modified version of SEMVER for its versioning me
 ## v2.11.1 - TBD
 - Add `GET /me/account/settings` and `PUT /me/account/settings` for account-level settings
 - Add `GET /me/user/settings` and `PUT /me/user/settings` for user-level display and formatting preferences
+- Add `GET /me/user/account/settings` and `PUT /me/user/account/settings` for settings specific to a user and budgeting account
+from `GET /me/account/settings` and `PUT /me/account/settings` to `GET /me/user/account/settings` and `PUT /me/user/account/settings`
+- Add `include_pending_in_totals` to `GET /me/account/settings` and `PUT /me/account/settings`
+- Add `default_manual_account_id` to `GET /me/user/account/settings` and `PUT /me/user/account/settings`
 - Document `GET /budgets/settings` response schema publicly; change `budget_period_quantity` to integer
 
 ## v2.11.0 - Jul 31, 2026