ynab 4.9.0 → 5.1.0

data/open_api_spec.yaml

@@ -5,7 +5,7 @@ info:
     and relies upon HTTPS for transport. We respond with meaningful HTTP
     response codes and if an error occurs, we include error details in the
     response body.  API Documentation is at https://api.ynab.com
-  version: 1.78.0
+  version: 1.83.0
 servers:
   - url: https://api.ynab.com/v1
 security:
@@ -51,7 +51,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/UserResponse"
-  /budgets:
+  /plans:
     get:
       tags:
         - Plans
@@ -77,7 +77,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
-  /budgets/{plan_id}:
+  /plans/{plan_id}:
     get:
       tags:
         - Plans
@@ -114,7 +114,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
-  /budgets/{plan_id}/settings:
+  /plans/{plan_id}/settings:
     get:
       tags:
         - Plans
@@ -143,7 +143,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
-  /budgets/{plan_id}/accounts:
+  /plans/{plan_id}/accounts:
     get:
       tags:
         - Accounts
@@ -216,7 +216,7 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
       x-codegen-request-body-name: data
-  /budgets/{plan_id}/accounts/{account_id}:
+  /plans/{plan_id}/accounts/{account_id}:
     get:
       tags:
         - Accounts
@@ -252,7 +252,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
-  /budgets/{plan_id}/categories:
+  /plans/{plan_id}/categories:
     get:
       tags:
         - Categories
@@ -327,7 +327,7 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
       x-codegen-request-body-name: data
-  /budgets/{plan_id}/categories/{category_id}:
+  /plans/{plan_id}/categories/{category_id}:
     get:
       tags:
         - Categories
@@ -406,7 +406,7 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
       x-codegen-request-body-name: data
-  /budgets/{plan_id}/months/{month}/categories/{category_id}:
+  /plans/{plan_id}/months/{month}/categories/{category_id}:
     get:
       tags:
         - Categories
@@ -504,7 +504,7 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
       x-codegen-request-body-name: data
-  /budgets/{plan_id}/category_groups:
+  /plans/{plan_id}/category_groups:
     post:
       tags:
         - Categories
@@ -542,7 +542,7 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
       x-codegen-request-body-name: data
-  /budgets/{plan_id}/category_groups/{category_group_id}:
+  /plans/{plan_id}/category_groups/{category_group_id}:
     patch:
       tags:
         - Categories
@@ -586,7 +586,7 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
       x-codegen-request-body-name: data
-  /budgets/{plan_id}/payees:
+  /plans/{plan_id}/payees:
     get:
       tags:
         - Payees
@@ -622,7 +622,44 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
-  /budgets/{plan_id}/payees/{payee_id}:
+    post:
+      tags:
+        - Payees
+      summary: Create a payee
+      description: Creates a new payee
+      operationId: createPayee
+      parameters:
+        - name: plan_id
+          in: path
+          description: 'The id of the plan. "last-used" can be used to specify the last
+            used plan and "default" can be used if default plan selection is
+            enabled (see: https://api.ynab.com/#oauth-default-plan).'
+          required: true
+          schema:
+            type: string
+      requestBody:
+        description: The payee to create
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PostPayeeWrapper"
+        required: true
+      responses:
+        "201":
+          description: The payee was successfully created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SavePayeeResponse"
+        "400":
+          description: The request could not be understood due to malformed syntax or
+            validation error(s)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+      x-codegen-request-body-name: data
+  /plans/{plan_id}/payees/{payee_id}:
     get:
       tags:
         - Payees
@@ -700,7 +737,7 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
       x-codegen-request-body-name: data
-  /budgets/{plan_id}/payee_locations:
+  /plans/{plan_id}/payee_locations:
     get:
       tags:
         - Payee Locations
@@ -729,7 +766,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
-  /budgets/{plan_id}/payee_locations/{payee_location_id}:
+  /plans/{plan_id}/payee_locations/{payee_location_id}:
     get:
       tags:
         - Payee Locations
@@ -764,7 +801,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
-  /budgets/{plan_id}/payees/{payee_id}/payee_locations:
+  /plans/{plan_id}/payees/{payee_id}/payee_locations:
     get:
       tags:
         - Payee Locations
@@ -799,7 +836,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
-  /budgets/{plan_id}/months:
+  /plans/{plan_id}/months:
     get:
       tags:
         - Months
@@ -835,7 +872,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
-  /budgets/{plan_id}/months/{month}:
+  /plans/{plan_id}/months/{month}:
     get:
       tags:
         - Months
@@ -872,7 +909,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
-  /budgets/{plan_id}/money_movements:
+  /plans/{plan_id}/money_movements:
     get:
       tags:
         - Money Movements
@@ -901,7 +938,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
-  /budgets/{plan_id}/months/{month}/money_movements:
+  /plans/{plan_id}/months/{month}/money_movements:
     get:
       tags:
         - Money Movements
@@ -938,7 +975,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
-  /budgets/{plan_id}/money_movement_groups:
+  /plans/{plan_id}/money_movement_groups:
     get:
       tags:
         - Money Movements
@@ -967,7 +1004,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
-  /budgets/{plan_id}/months/{month}/money_movement_groups:
+  /plans/{plan_id}/months/{month}/money_movement_groups:
     get:
       tags:
         - Money Movements
@@ -1004,7 +1041,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
-  /budgets/{plan_id}/transactions:
+  /plans/{plan_id}/transactions:
     get:
       tags:
         - Transactions
@@ -1158,7 +1195,7 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
       x-codegen-request-body-name: data
-  /budgets/{plan_id}/transactions/import:
+  /plans/{plan_id}/transactions/import:
     post:
       tags:
         - Transactions
@@ -1200,7 +1237,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
-  /budgets/{plan_id}/transactions/{transaction_id}:
+  /plans/{plan_id}/transactions/{transaction_id}:
     get:
       tags:
         - Transactions
@@ -1312,7 +1349,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
-  /budgets/{plan_id}/accounts/{account_id}/transactions:
+  /plans/{plan_id}/accounts/{account_id}/transactions:
     get:
       tags:
         - Transactions
@@ -1371,7 +1408,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
-  /budgets/{plan_id}/categories/{category_id}/transactions:
+  /plans/{plan_id}/categories/{category_id}/transactions:
     get:
       tags:
         - Transactions
@@ -1430,7 +1467,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
-  /budgets/{plan_id}/payees/{payee_id}/transactions:
+  /plans/{plan_id}/payees/{payee_id}/transactions:
     get:
       tags:
         - Transactions
@@ -1489,7 +1526,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
-  /budgets/{plan_id}/months/{month}/transactions:
+  /plans/{plan_id}/months/{month}/transactions:
     get:
       tags:
         - Transactions
@@ -1549,7 +1586,7 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
-  /budgets/{plan_id}/scheduled_transactions:
+  /plans/{plan_id}/scheduled_transactions:
     get:
       tags:
         - Scheduled Transactions
@@ -1623,7 +1660,7 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
       x-codegen-request-body-name: data
-  /budgets/{plan_id}/scheduled_transactions/{scheduled_transaction_id}:
+  /plans/{plan_id}/scheduled_transactions/{scheduled_transaction_id}:
     get:
       tags:
         - Scheduled Transactions
@@ -1827,14 +1864,14 @@ components:
       properties:
         data:
           required:
-            - budgets
+            - plans
           type: object
           properties:
-            budgets:
+            plans:
               type: array
               items:
                 $ref: "#/components/schemas/PlanSummary"
-            default_budget:
+            default_plan:
               allOf:
                 - $ref: "#/components/schemas/PlanSummary"
               nullable: true
@@ -1879,11 +1916,11 @@ components:
       properties:
         data:
           required:
-            - budget
+            - plan
             - server_knowledge
           type: object
           properties:
-            budget:
+            plan:
               $ref: "#/components/schemas/PlanDetail"
             server_knowledge:
               type: integer
@@ -1897,7 +1934,7 @@ components:
             accounts:
               type: array
               items:
-                $ref: "#/components/schemas/Account"
+                $ref: "#/components/schemas/AccountBase"
             payees:
               type: array
               items:
@@ -1913,27 +1950,27 @@ components:
             categories:
               type: array
               items:
-                $ref: "#/components/schemas/Category"
+                $ref: "#/components/schemas/CategoryBase"
             months:
               type: array
               items:
-                $ref: "#/components/schemas/MonthDetail"
+                $ref: "#/components/schemas/MonthDetailBase"
             transactions:
               type: array
               items:
-                $ref: "#/components/schemas/TransactionSummary"
+                $ref: "#/components/schemas/TransactionSummaryBase"
             subtransactions:
               type: array
               items:
-                $ref: "#/components/schemas/SubTransaction"
+                $ref: "#/components/schemas/SubTransactionBase"
             scheduled_transactions:
               type: array
               items:
-                $ref: "#/components/schemas/ScheduledTransactionSummary"
+                $ref: "#/components/schemas/ScheduledTransactionSummaryBase"
             scheduled_subtransactions:
               type: array
               items:
-                $ref: "#/components/schemas/ScheduledSubTransaction"
+                $ref: "#/components/schemas/ScheduledSubTransactionBase"
     PlanSettingsResponse:
       required:
         - data
@@ -1987,7 +2024,7 @@ components:
           properties:
             account:
               $ref: "#/components/schemas/Account"
-    Account:
+    AccountBase:
       required:
         - balance
         - cleared_balance
@@ -2067,6 +2104,32 @@ components:
           type: boolean
           description: Whether or not the account has been deleted.  Deleted accounts will
             only be included in delta requests.
+    Account:
+      allOf:
+        - $ref: "#/components/schemas/AccountBase"
+        - type: object
+          properties:
+            balance_formatted:
+              type: string
+              description: The current available balance of the account formatted in the plan's currency format
+            balance_currency:
+              type: number
+              format: double
+              description: The current available balance of the account as a decimal currency amount
+            cleared_balance_formatted:
+              type: string
+              description: The current cleared balance of the account formatted in the plan's currency format
+            cleared_balance_currency:
+              type: number
+              format: double
+              description: The current cleared balance of the account as a decimal currency amount
+            uncleared_balance_formatted:
+              type: string
+              description: The current uncleared balance of the account formatted in the plan's currency format
+            uncleared_balance_currency:
+              type: number
+              format: double
+              description: The current uncleared balance of the account as a decimal currency amount
     PostAccountWrapper:
       required:
         - account
@@ -2085,7 +2148,7 @@ components:
           type: string
           description: The name of the account
         type:
-          $ref: "#/components/schemas/AccountType"
+          $ref: "#/components/schemas/SaveAccountType"
         balance:
           type: integer
           description: The current balance of the account in milliunits format
@@ -2097,6 +2160,16 @@ components:
       additionalProperties:
         type: integer
         format: int64
+    SaveAccountType:
+      type: string
+      description: The type of account to create or update
+      enum:
+        - checking
+        - savings
+        - cash
+        - creditCard
+        - otherAsset
+        - otherLiability
     AccountType:
       type: string
       description: The type of account
@@ -2178,7 +2251,7 @@ components:
           type: boolean
           description: Whether or not the category group has been deleted.  Deleted
             category groups will only be included in delta requests.
-    Category:
+    CategoryBase:
       required:
         - activity
         - balance
@@ -2357,6 +2430,76 @@ components:
           type: boolean
           description: Whether or not the category has been deleted.  Deleted categories
             will only be included in delta requests.
+    Category:
+      allOf:
+        - $ref: "#/components/schemas/CategoryBase"
+        - type: object
+          properties:
+            balance_formatted:
+              type: string
+              description: Available balance of the category formatted in the plan's currency format
+            balance_currency:
+              type: number
+              format: double
+              description: Available balance of the category as a decimal currency amount
+            activity_formatted:
+              type: string
+              description: Activity of the category formatted in the plan's currency format
+            activity_currency:
+              type: number
+              format: double
+              description: Activity of the category as a decimal currency amount
+            budgeted_formatted:
+              type: string
+              description: Assigned (budgeted) amount of the category formatted in the plan's currency format
+            budgeted_currency:
+              type: number
+              format: double
+              description: Assigned (budgeted) amount of the category as a decimal currency amount
+            goal_target_formatted:
+              type:
+                - string
+                - "null"
+              description: The goal target amount formatted in the plan's currency format
+            goal_target_currency:
+              type:
+                - number
+                - "null"
+              format: double
+              description: The goal target amount as a decimal currency amount
+            goal_under_funded_formatted:
+              type:
+                - string
+                - "null"
+              description: The goal underfunded amount formatted in the plan's currency format
+            goal_under_funded_currency:
+              type:
+                - number
+                - "null"
+              format: double
+              description: The goal underfunded amount as a decimal currency amount
+            goal_overall_funded_formatted:
+              type:
+                - string
+                - "null"
+              description: The total amount funded towards the goal formatted in the plan's currency format
+            goal_overall_funded_currency:
+              type:
+                - number
+                - "null"
+              format: double
+              description: The total amount funded towards the goal as a decimal currency amount
+            goal_overall_left_formatted:
+              type:
+                - string
+                - "null"
+              description: The amount of funding still needed to complete the goal formatted in the plan's currency format
+            goal_overall_left_currency:
+              type:
+                - number
+                - "null"
+              format: double
+              description: The amount of funding still needed to complete the goal as a decimal currency amount
     SaveCategoryResponse:
       required:
         - data
@@ -2784,7 +2927,7 @@ components:
               type: integer
               description: The knowledge of the server
               format: int64
-    TransactionSummary:
+    TransactionSummaryBase:
       required:
         - account_id
         - amount
@@ -2894,6 +3037,19 @@ components:
           type: boolean
           description: Whether or not the transaction has been deleted.  Deleted
             transactions will only be included in delta requests.
+    TransactionSummary:
+      allOf:
+        - $ref: "#/components/schemas/TransactionSummaryBase"
+        - type: object
+          properties:
+            amount_formatted:
+              type: string
+              description: The transaction amount formatted in the plan's currency format
+            amount_currency:
+              type: number
+              format: double
+              description: The transaction amount as a decimal currency amount
+
     TransactionDetail:
       allOf:
         - $ref: "#/components/schemas/TransactionSummary"
@@ -2951,6 +3107,23 @@ components:
               type: string
               description: The name of the category.  If a split transaction, this will be
                 'Split'.
+    PostPayeeWrapper:
+      required:
+        - payee
+      type: object
+      properties:
+        payee:
+          $ref: "#/components/schemas/PostPayee"
+    PostPayee:
+      required:
+        - name
+      type: object
+      properties:
+        name:
+          type: string
+          nullable: false
+          maxLength: 500
+          description: The name of the payee.
     PatchPayeeWrapper:
       required:
         - payee
@@ -2965,7 +3138,7 @@ components:
           type: string
           nullable: false
           maxLength: 500
-          description: The name of the payee. The name must be a maximum of 500 characters.
+          description: The name of the payee.
     PostCategoryGroupWrapper:
       required:
         - category_group
@@ -3023,9 +3196,9 @@ components:
             - integer
             - "null"
           description: The goal target amount in milliunits format.  If value is specified
-            and goal has not already been configured for category, a monthly
-            'Needed for Spending' goal will be created for the category with
-            this target amount.
+            and goal has not already been configured for category, a monthly goal
+            will be created for the category with this target amount.  If goal_type is
+            not specified, it will default to 'NEED' or 'MF' for Credit Card Payment categories.
           format: int64
         goal_target_date:
           type:
@@ -3033,6 +3206,13 @@ components:
             - "null"
           description: The goal target date in ISO format (e.g. 2016-12-01).
           format: date
+        goal_needs_whole_amount:
+          type:
+            - boolean
+            - "null"
+          description: Whether the goal requires the full target amount each period. Only supported for 'NEED' goals.
+            When true, the goal is configured as 'Set aside another...'.
+            When false, the goal is configured as 'Refill up to...'.
     ExistingCategory:
       allOf:
         - $ref: "#/components/schemas/SaveCategory"
@@ -3112,7 +3292,7 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/SaveTransactionWithOptionalFields"
-    SubTransaction:
+    SubTransactionBase:
       required:
         - amount
         - deleted
@@ -3166,6 +3346,18 @@ components:
           type: boolean
           description: Whether or not the subtransaction has been deleted.  Deleted
             subtransactions will only be included in delta requests.
+    SubTransaction:
+      allOf:
+        - $ref: "#/components/schemas/SubTransactionBase"
+        - type: object
+          properties:
+            amount_formatted:
+              type: string
+              description: The subtransaction amount formatted in the plan's currency format
+            amount_currency:
+              type: number
+              format: double
+              description: The subtransaction amount as a decimal currency amount
     ScheduledTransactionsResponse:
       required:
         - data
@@ -3265,7 +3457,7 @@ components:
           $ref: "#/components/schemas/TransactionFlagColor"
         frequency:
           $ref: "#/components/schemas/ScheduledTransactionFrequency"
-    ScheduledTransactionSummary:
+    ScheduledTransactionSummaryBase:
       required:
         - account_id
         - amount
@@ -3339,6 +3531,18 @@ components:
           type: boolean
           description: Whether or not the scheduled transaction has been deleted.  Deleted
             scheduled transactions will only be included in delta requests.
+    ScheduledTransactionSummary:
+      allOf:
+        - $ref: "#/components/schemas/ScheduledTransactionSummaryBase"
+        - type: object
+          properties:
+            amount_formatted:
+              type: string
+              description: The scheduled transaction amount formatted in the plan's currency format
+            amount_currency:
+              type: number
+              format: double
+              description: The scheduled transaction amount as a decimal currency amount
     ScheduledTransactionDetail:
       allOf:
         - $ref: "#/components/schemas/ScheduledTransactionSummary"
@@ -3364,7 +3568,7 @@ components:
               description: If a split scheduled transaction, the subtransactions.
               items:
                 $ref: "#/components/schemas/ScheduledSubTransaction"
-    ScheduledSubTransaction:
+    ScheduledSubTransactionBase:
       required:
         - amount
         - deleted
@@ -3416,6 +3620,18 @@ components:
           description: Whether or not the scheduled subtransaction has been deleted.
             Deleted scheduled subtransactions will only be included in delta
             requests.
+    ScheduledSubTransaction:
+      allOf:
+        - $ref: "#/components/schemas/ScheduledSubTransactionBase"
+        - type: object
+          properties:
+            amount_formatted:
+              type: string
+              description: The scheduled subtransaction amount formatted in the plan's currency format
+            amount_currency:
+              type: number
+              format: double
+              description: The scheduled subtransaction amount as a decimal currency amount
     MonthSummariesResponse:
       required:
         - data
@@ -3447,7 +3663,7 @@ components:
           properties:
             month:
               $ref: "#/components/schemas/MonthDetail"
-    MonthSummary:
+    MonthSummaryBase:
       required:
         - activity
         - budgeted
@@ -3492,6 +3708,52 @@ components:
           type: boolean
           description: Whether or not the month has been deleted.  Deleted months will
             only be included in delta requests.
+    MonthSummary:
+      allOf:
+        - $ref: "#/components/schemas/MonthSummaryBase"
+        - type: object
+          properties:
+            income_formatted:
+              type: string
+              description: The total income formatted in the plan's currency format
+            income_currency:
+              type: number
+              format: double
+              description: The total income as a decimal currency amount
+            budgeted_formatted:
+              type: string
+              description: The total amount assigned formatted in the plan's currency format
+            budgeted_currency:
+              type: number
+              format: double
+              description: The total amount assigned as a decimal currency amount
+            activity_formatted:
+              type: string
+              description: The total activity amount formatted in the plan's currency format
+            activity_currency:
+              type: number
+              format: double
+              description: The total activity amount as a decimal currency amount
+            to_be_budgeted_formatted:
+              type: string
+              description: The available amount for 'Ready to Assign' formatted in the plan's currency format
+            to_be_budgeted_currency:
+              type: number
+              format: double
+              description: The available amount for 'Ready to Assign' as a decimal currency amount
+    MonthDetailBase:
+      allOf:
+        - $ref: "#/components/schemas/MonthSummaryBase"
+        - required:
+            - categories
+          type: object
+          properties:
+            categories:
+              type: array
+              description: The plan month categories.  Amounts (budgeted, activity, balance,
+                etc.) are specific to the {month} parameter specified.
+              items:
+                $ref: "#/components/schemas/CategoryBase"
     MonthDetail:
       allOf:
         - $ref: "#/components/schemas/MonthSummary"
@@ -3567,7 +3829,7 @@ components:
               type: integer
               description: The knowledge of the server
               format: int64
-    MoneyMovement:
+    MoneyMovementBase:
       required:
         - id
         - amount
@@ -3621,6 +3883,18 @@ components:
           type: integer
           description: The amount of the money movement in milliunits format
           format: int64
+    MoneyMovement:
+      allOf:
+        - $ref: "#/components/schemas/MoneyMovementBase"
+        - type: object
+          properties:
+            amount_formatted:
+              type: string
+              description: The money movement amount formatted in the plan's currency format
+            amount_currency:
+              type: number
+              format: double
+              description: The money movement amount as a decimal currency amount
     MoneyMovementGroupsResponse:
       required:
         - data