@lunch-money/developer-docs 2.11.0-preview.10

package/v1/_categories.md

@@ -0,0 +1,407 @@
+# Categories
+
+<aside class="notice">
+This API (v1) will not progress to a generally available state. For new projects, we recommend using the <a href="/v2/docs#tag/categories">v2 API</a>, which is in open alpha and actively maintained.
+</aside>
+
+## Categories Object
+
+Attribute Name      | Type             | Nullable | Description
+------------------- | ---------------- | -------- | --------------------------------------------------------------------
+id                  | number           | false    | A unique identifier for the category.
+name                | string           | false    | The name of the category. Must be between 1 and 40 characters.
+description         | string           | true     | The description of the category. Must not exceed 140 characters.
+is_income           | boolean          | false    | If true, the transactions in this category will be treated as income.
+exclude_from_budget | boolean          | false    | If true, the transactions in this category will be excluded from the budget.
+exclude_from_totals | boolean          | false    | If true, the transactions in this category will be excluded from totals.
+archived            | boolean          | true     | If true, the category is archived and not displayed in relevant areas of the Lunch Money app.
+archived_on         | string           | true     | The date and time of when the category was last archived (in the ISO 8601 extended format).
+updated_at          | string           | true     | The date and time of when the category was last updated (in the ISO 8601 extended format).
+created_at          | string           | true     | The date and time of when the category was created (in the ISO 8601 extended format).
+is_group            | boolean          | false    | If true, the category is a group that can be a parent to other categories.
+group_id            | number           | true     | The ID of a category group (or null if the category doesn't belong to a category group).
+order               | number           | true     | Numerical ordering of categories
+children            | array of objects | true     | For category groups, this will populate with the categories nested within and include id, name, description and created_at fields.
+group_category_name | string           | true     | For grouped categories, the name of the category group
+
+## Get All Categories
+
+Use this endpoint to get a flattened list of all categories in alphabetical order associated with the user's account.
+
+```json
+{
+  "categories": [
+    {
+      "id": 83,
+      "name": "Test 1",
+      "description": "Test description",
+      "is_income": false,
+      "exclude_from_budget": true,
+      "exclude_from_totals": false,
+      "updated_at": "2020-01-28T09:49:03.225Z",
+      "created_at": "2020-01-28T09:49:03.225Z",
+      "is_group": false,
+      "group_id": null,
+      "order": 0
+    },
+    {
+      "id": 84,
+      "name": "Test 2",
+      "description": null,
+      "is_income": true,
+      "exclude_from_budget": false,
+      "exclude_from_totals": true,
+      "updated_at": "2020-01-28T09:49:03.238Z",
+      "created_at": "2020-01-28T09:49:03.238Z",
+      "is_group": true,
+      "group_id": 83,
+      "order": 1,
+      "children": [
+        {
+          "id": 315162,
+          "name": "Alcohol, Bars",
+          "description": null,
+          "created_at": "2022-03-06T20:11:36.066Z"
+        },
+        {
+          "id": 315169,
+          "name": "Groceries",
+          "description": null,
+          "created_at": "2022-03-06T20:11:36.120Z"
+        },
+        {
+          "id": 315172,
+          "name": "Restaurants",
+          "description": null,
+          "created_at": "2022-03-06T20:11:36.146Z"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### HTTP Request
+
+`GET https://api.lunchmoney.dev/v1/categories`
+
+### Query Parameters
+
+Parameter | Type   | Required | Default   | Description
+--------- | ------ | -------- | --------- | --------------------------------------------------------------------------
+format    | string | false    | flattened | Can either `flattened` or `nested`. If `flattened`, returns a singular array of categories, ordered alphabetically. If `nested`, returns top-level categories (either category groups or categories not part of a category group) in an array. Subcategories are nested within the category group under the property `children`.
+
+## Get Single Category
+
+Use this endpoint to get hydrated details on a single category. Note that if this category is part of a category group, its properties (is_income, exclude_from_budget, exclude_from_totals) will inherit from the category group.
+
+```json
+{
+  "id": 315358,
+  "name": "Food & Drink",
+  "description": null,
+  "is_income": false,
+  "exclude_from_budget": false,
+  "exclude_from_totals": false,
+  "archived": false,
+  "archived_on": null,
+  "is_group": true,
+  "group_id": null,
+  "order": 5,
+  "children": [
+    {
+      "id": 315162,
+      "name": "Alcohol, Bars",
+      "description": null,
+      "created_at": "2022-03-06T20:11:36.066Z"
+    },
+    {
+      "id": 315169,
+      "name": "Groceries",
+      "description": null,
+      "created_at": "2022-03-06T20:11:36.120Z"
+    },
+    {
+      "id": 315172,
+      "name": "Restaurants",
+      "description": null,
+      "created_at": "2022-03-06T20:11:36.146Z"
+    }
+  ]
+}
+```
+
+### HTTP Request
+
+`GET https://api.lunchmoney.dev/v1/categories/:category_id`
+
+## Create Category
+
+Use this endpoint to create a single category
+
+> Example 200 Response
+>
+> Returns the ID of the newly-created category
+
+```json
+{
+  "category_id": 26213
+}
+```
+
+> Example Error Response (sends as 200)
+
+```json
+{ "error": "Missing category name." }
+```
+
+```json
+{ "error": "Category name must be less than 40 characters." }
+```
+
+```json
+{ "error": "Category description must be less than 140 characters." }
+```
+
+```json
+{
+  "error": "Operation error occurred. Please try again or contact support@lunchmoney.app for assistance."
+}
+```
+
+### HTTP Request
+
+`POST https://api.lunchmoney.dev/v1/categories`
+
+Parameter           | Type    | Required | Default | Description
+------------------- | ------- | -------- | ------- | -------------------------------------------------------------------
+name                | string  | true     | -       | Name of category. Must be between 1 and 40 characters.
+description         | string  | false    | -       | Description of category. Must be less than 140 categories.
+is_income           | boolean | false    | false   | Whether or not transactions in this category should be treated as income.
+exclude_from_budget | boolean | false    | false   | Whether or not transactions in this category should be excluded from budgets.
+exclude_from_totals | boolean | false    | false   | Whether or not transactions in this category should be excluded from calculated totals.
+archived            | boolean | false    | false   | Whether or not category should be archived.
+group_id            | number  | false    | -       | Assigns the newly-created category to an existing category group.
+
+## Create Category Group
+
+Use this endpoint to create a single category group
+
+> Example 200 Response
+>
+> Returns the ID of the newly-created category group
+
+```json
+{
+  "category_id": 26213
+}
+```
+
+> Example Error Response (sends as 200)
+
+```json
+{ "error": "Missing category name." }
+```
+
+```json
+{
+  "error": "A category with the same name (sample_duplicate_name) already exists."
+}
+```
+
+```json
+{
+  "error": "The following category id(s) could not be added as a group because you do not have permissions for this category, or it is already a category group: 3893"
+}
+```
+
+### HTTP Request
+
+`POST https://api.lunchmoney.dev/v1/categories/group`
+
+Parameter           | Type             | Required | Default | Description
+------------------- | ---------------- | -------- | ------- | ----------------------------------------------------------
+name                | string           | true     | -       | Name of category. Must be between 1 and 40 characters.
+description         | string           | false    | -       | Description of category. Must be less than 140 categories.
+is_income           | boolean          | false    | false   | Whether or not transactions in this category should be treated as income.
+exclude_from_budget | boolean          | false    | false   | Whether or not transactions in this category should be excluded from budgets.
+exclude_from_totals | boolean          | false    | false   | Whether or not transactions in this category should be excluded from calculated totals.
+category_ids        | array of numbers | false    | -       | Array of category_id to include in the category group.
+new_categories      | array of strings | false    | -       | Array of strings representing new categories to create and subsequently include in the category group.
+
+## Update Category
+
+Use this endpoint to update the properties for a single category or category group
+
+> Example 200 Response
+>
+> If successfully updated, returns true
+
+```json
+true
+```
+
+> Example Error Response (sends as 200)
+
+```json
+{ "error": "No valid fields to update for this category." }
+```
+
+```json
+{ "error": "You may not set the is_group property for an existing category." }
+```
+
+```json
+{
+  "error": "This category cannot be assigned a group because it is a category group."
+}
+```
+
+```json
+{
+  "error": "Operation error occurred. Please try again or contact support@lunchmoney.app for assistance."
+}
+```
+
+### HTTP Request
+
+`PUT https://api.lunchmoney.dev/v1/categories/:category_id`
+
+Parameter           | Type    | Required | Default | Description
+------------------- | ------- | -------- | ------- | -------------------------------------------------------------------
+name                | string  | false    | -       | Name of category. Must be between 1 and 40 characters.
+description         | string  | false    | -       | Description of category. Must be less than 140 categories.
+is_income           | boolean | false    | false   | Whether or not transactions in this category should be treated as income.
+exclude_from_budget | boolean | false    | false   | Whether or not transactions in this category should be excluded from budgets.
+exclude_from_totals | boolean | false    | false   | Whether or not transactions in this category should be excluded from calculated totals.
+archived            | boolean | false    | false   | Whether or not category should be archived.
+group_id            | number  | false    | false   | For a category, set the group_id to include it in a category group
+
+## Add to Category Group
+
+Use this endpoint to add categories (either existing or new) to a single category group
+
+> Example 200 Response
+>
+> Returns the hydrated object for the category group
+
+```json
+{
+  "id": 315358,
+  "name": "Food & Drink",
+  "description": null,
+  "is_income": false,
+  "exclude_from_budget": false,
+  "exclude_from_totals": false,
+  "is_group": true,
+  "group_id": null,
+  "children": [
+    {
+      "id": 315162,
+      "name": "Alcohol, Bars",
+      "description": null,
+      "created_at": "2022-03-06T20:11:36.066Z"
+    },
+    {
+      "id": 315164,
+      "name": "Coffee Shops",
+      "description": null,
+      "created_at": "2022-03-06T20:11:36.082Z"
+    },
+    {
+      "id": 315169,
+      "name": "Groceries",
+      "description": null,
+      "created_at": "2022-03-06T20:11:36.120Z"
+    },
+    {
+      "id": 315172,
+      "name": "Restaurants",
+      "description": null,
+      "created_at": "2022-03-06T20:11:36.146Z"
+    }
+  ]
+}
+```
+
+> Example Error Response (sends as 200)
+
+```json
+{
+  "error": "The following category id(s) could not be added as a group because you do not have permissions for this category, or it is already a category group: 3280"
+}
+```
+
+```json
+{
+  "error": "Operation error occurred. Please try again or contact support@lunchmoney.app for assistance."
+}
+```
+
+### HTTP Request
+
+`POST https://api.lunchmoney.dev/v1/categories/group/:group_id/add`
+
+Parameter      | Type             | Required | Default | Description
+-------------- | ---------------- | -------- | ------- | ---------------------------------------------------------------
+category_ids   | array of numbers | false    | -       | Array of category_id to include in the category group.
+new_categories | array of strings | false    | -       | Array of strings representing new categories to create and subsequently include in the category group.
+
+## Delete Category
+
+Use this endpoint to delete a single category or category group. This will only work if there are no dependencies, such as existing budgets for the category, categorized transactions, categorized recurring items, etc. If there are dependents, this endpoint will return what the dependents are and how many there are.
+
+> Example 200 Response
+>
+> If successfully deleted, returns true
+
+```json
+true
+```
+
+> Example Error Response (sends as 200)
+
+```json
+{
+  "dependents": {
+    "category_name": "Food & Drink",
+    "budget": 4,
+    "category_rules": 0,
+    "transactions": 43,
+    "children": 7,
+    "recurring": 0
+  }
+}
+```
+
+### HTTP Request
+
+`DELETE https://api.lunchmoney.dev/v1/categories/:category_id`
+
+## Force Delete Category
+
+Use this endpoint to force delete a single category or category group and along with it, disassociate the category from any transactions, recurring items, budgets, etc.
+
+_Note: it is best practice to first try the `Delete Category` endpoint to ensure you don't accidentally delete any data. Disassociation/deletion of the data arising from this endpoint is irreversible!_
+
+> Example 200 Response
+>
+> If successfully deleted, returns true
+
+```json
+true
+```
+
+> Example Error Response (sends as 200)
+
+```json
+{
+  "error": "Operation error occurred. Please try again or contact support@lunchmoney.app for assistance."
+}
+```
+
+### HTTP Request
+
+`DELETE https://api.lunchmoney.dev/v1/categories/:category_id/force`
+
+---

package/v1/_changelog.md

@@ -0,0 +1,102 @@
+# Changelog
+
+A log of changes. Breaking changes will be denoted with 🚨
+## Feb 6, 2025
+- The [Assets Object](#assets-object) and [Plaid Accounts Object](#plaid-accounts-object) now include a `to_base` property which shows the account balance converted to the user's primary currency.
+
+## Feb 3, 2025
+- The [Update Transaction Object](#update-transaction-object) now accepts a `plaid_account_id` allowing developers to update existing transactions associated with plaid accounts or to move transactions to a plaid account if the "Allow Modifications to Transactions" property is set.
+- The bug in the [GET /transactions/{id}](#get-single-transaction) endpoint where the `debit_as_negative` query param was ignored has been fixed. 
+
+## Dec 20, 2024
+- The [Transaction Insert Object](#transaction-object-to-insert) now accepts a `plaid_account_id` allowing developers to insert transactions associated with plaid accounts if the "Allow Modifications to Transactions" property is set.
+- The bug that prevented users from inserting transactions with the same `asset_id`/`external_id` as a previously deleted transaction has been fixed.
+
+## June 15, 2024
+- New endpoint: [GET /v1/recurring_items](#get-recurring-items)
+- Deprecated the [GET /v1/recurring_expenses](#get-recurring-expenses) endpoint in favor of the new recurring_items endpoint
+
+## March 27, 2024
+
+### Updated
+
+- 🚨 Deprecated `transaction_id` in [Recurring Expenses Object](#recurring-expenses-object) (temporarily... it will come back in another form)
+- 🚨 Deprecated special statuses for transactions (`recurring` and `recurring_suggested`)
+
+## January 18, 2024
+
+### New
+
+- New endpoint: [GET /v1/transactions/group](#get-transaction-group)
+- New fields for [Transaction object](#transaction-object) and deprecated query parameter (`group_id`) and fields (`type`, `subtype`, `quantity`, `fee`, `price`)
+
+## December 20, 2023
+
+### New
+
+- New endpoint: [POST /v1/plaid_accounts/fetch](#trigger-fetch-from-plaid) (experimental)
+
+## October 8, 2023
+
+### Updated
+
+- New fields for [GET /v1/categories](#get-all-categories): order
+- New option for [GET /v1/categories](#get-all-categories): format (flattened or nested)
+
+## June 22, 2022
+
+### New
+
+- New endpoint: [POST /v1/transactions/unsplit](#unsplit-transactions)
+
+## June 4, 2022
+
+### New
+
+- Lots of new endpoints for [categories](#categories) with support for [category groups](#create-category-group)
+
+## August 31, 2021
+
+### Updated
+
+- New fields for [GET /v1/budgets](#get-budget-summary): config
+
+## June 9, 2021
+
+### New
+
+- New endpoint: [POST /v1/transactions/group](#create-transaction-group)
+- New endpoint: [DELETE /v1/transactions/group/:transaction_id](#delete-transaction-group)
+
+### Updated
+
+- New option for [POST /v1/transactions](#insert-transactions) and [PUT /v1/transactions](#update-transaction): skip_balance_update
+- New fields for [GET /v1/transactions](#get-all-transactions): original_name, type, subtype, fees, price, quantity
+- New filter options for [GET /v1/transactions](#get-all-transactions): status, is_group, group_id
+
+## May 27, 2021
+
+### New
+
+- New endpoint: [GET /v1/budgets](#get-budget-summary)
+- New endpoint: [GET /v1/crypto](#get-all-crypto)
+- New endpoint: [PUT /v1/crypto/manual/:id](#update-manual-crypto-asset)
+
+### Updated
+
+- New fields for [GET /v1/assets](#get-all-assets): display_name and closed_on
+
+## March 28, 2020
+
+### New
+
+- Pagination options for [GET /v1/transactions](#get-all-transactions): limit and offset
+- Filter options for [GET /v1/transactions](#get-all-transactions): asset_id, recurring_id, plaid_account_id, tag_id, category_id
+- New endpoint: [GET /v1/budget](#get-all-tags)
+
+### Updated
+
+- Support for tags in [PUT /v1/transactions/:id](#update-transaction) and [POST /v1/transactions](#insert-transactions)
+- 🚨Split object for [splitting transactions](#update-transaction) is moved out of the Transactions object and to a higher-level. We will still support the split property for a few more weeks before removing it completely.
+
+---

package/v1/_crypto.md

@@ -0,0 +1,105 @@
+# Crypto
+
+<aside class="notice">
+The v2 API does not yet support crypto endpoints. Please continue using the v1 crypto API as documented here.
+</aside>
+
+## Crypto Object
+
+Attribute Name      | Type   | Nullable | Description
+------------------- | ----   | -------- | -----------
+id                  | number | true     | Unique identifier for a manual crypto account (no ID for synced accounts)
+zabo_account_id     | number | true     | Unique identifier for a synced crypto account (no ID for manual accounts, multiple currencies may have the same zabo_account_id)
+source              | string | false    | One of:<br/><ul><li>`synced`: this account is synced via a wallet, exchange, etc.</li><li>`manual`: this account balance is managed manually</li></ul>
+name                | string | false    | Name of the crypto asset
+display_name        | string | true     | Display name of the crypto asset (as set by user)
+balance             | string | false    | Current balance
+balance_as_of       | string | false    | Date/time the balance was last updated in ISO 8601 extended format
+currency            | string | false    | Abbreviation for the cryptocurrency
+status              | string | false    | The current status of the crypto account. Either active or in error.
+institution_name    | string | true     | Name of provider holding the asset
+created_at          | string | false    | Date/time the asset was created in ISO 8601 extended format
+to_base             | number | true     | The balance converted to the user's primary currency.
+
+## Get All Crypto
+
+Use this endpoint to get a list of all cryptocurrency assets associated with the user's account. Both crypto balances from synced and manual accounts will be returned.
+
+> Example 200 Response
+
+```json
+{
+    "crypto": [
+        {
+            "zabo_account_id": 544,
+            "source": "synced",
+            "created_at": "2020-07-27T11:53:02.722Z",
+            "name": "Dogecoin",
+            "display_name": null,
+            "balance": "1.902383849000000000",
+            "balance_as_of": "2021-05-21T00:05:36.000Z",
+            "currency": "doge",
+            "status": "active",
+            "institution_name": "MetaMask"
+        },
+        {
+            "id": 152,
+            "source": "manual",
+            "created_at": "2021-04-03T04:16:48.230Z",
+            "name": "Ether",
+            "display_name": "BlockFi - ETH",
+            "balance": "5.391445130000000000",
+            "balance_as_of": "2021-05-20T16:57:00.000Z",
+            "currency": "ETH",
+            "status": "active",
+            "institution_name": "BlockFi"
+        },
+    ]
+}
+```
+
+### HTTP Request
+
+`GET https://api.lunchmoney.dev/v1/crypto`
+
+## Update Manual Crypto Asset
+
+Use this endpoint to update a single manually-managed crypto asset (does not include assets received from syncing with your wallet/exchange/etc). These are denoted by `source: manual` from the GET call above.
+
+> Example 200 Response
+
+```json
+{
+    "id": 1,
+    "source": "manual",
+    "created_at": "2021-02-10T05:57:34.305Z",
+    "name": "Shiba Token",
+    "display_name": "SHIB",
+    "balance": "12.000000000000000000",
+    "currency": "SHIB",
+    "status": "active",
+    "institution_name": null
+}
+```
+
+> Example Error Response (sends as 200)
+
+```json
+{ "errors": [ "currency is invalid for crypto: fakecoin. It may not be supported yet. Request to get it supported via the app or support@lunchmoney.app" ] }
+```
+
+### HTTP Request
+
+`PUT https://api.lunchmoney.dev/v1/crypto/manual/:id`
+
+### Body Parameters
+
+Parameter        | Type   | Required | Default | Description
+---------        | ----   | -------- | ------- | -----------
+name             | string | false    | -       | Official or full name of the account. Max 45 characters
+display_name     | string | false    | -       | Display name for the account. Max 25 characters
+institution_name | string | false    | -       | Name of provider that holds the account. Max 50 characters
+balance          | number | false    | -       | Numeric value of the current balance of the account. Do not include any special characters aside from a decimal point!
+currency         | string | false    | -       | Cryptocurrency that is supported for manual tracking in our database
+
+---