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

package/v2/docs/migration-guide.md

@@ -0,0 +1,1143 @@
+# Migrating from API v1 to v2
+
+The v2 API was built with direct input from the Lunch Money developer community. Features and design decisions were shaped by feedback including:
+
+- <a href="https://lunchmoney.canny.io/developer-api/p/openapi-spec" target="_blank" rel="noopener noreferrer">OpenAPI Spec</a>
+- <a href="https://lunchmoney.canny.io/developer-api/p/delete-transaction-endpoint" target="_blank" rel="noopener noreferrer">Delete transaction endpoint</a>
+- <a href="https://feedback.lunchmoney.app/developer-api/p/expose-api-for-the-v2-budget-feature" target="_blank" rel="noopener noreferrer">Expose API for the v2 Budget feature</a>
+- <a href="https://lunchmoney.canny.io/developer-api/p/create-tags-endpoint" target="_blank" rel="noopener noreferrer">Create Tags Endpoint</a>
+- <a href="https://lunchmoney.canny.io/developer-api/p/allow-partial-transaction-insertions-or-upserts" target="_blank" rel="noopener noreferrer">Insert Transactions even when there are some duplicates</a>
+- <a href="https://lunchmoney.canny.io/developer-api/p/improve-error-messaging-in-api" target="_blank" rel="noopener noreferrer">Improve error messaging in API</a>
+- <a href="https://lunchmoney.canny.io/developer-api/p/created-at-updated-at" target="_blank" rel="noopener noreferrer">Created At + Updated At for all objects</a>
+- <a href="https://feedback.lunchmoney.app/developer-api/p/special-characters-in-names-arent-handled-well-by-some-apis" target="_blank" rel="noopener noreferrer">Special Characters in names aren't handled well by some APIs</a>
+- <a href="https://feedback.lunchmoney.app/developer-api/p/add-last-updated-after-filter-to-transactions-api" target="_blank" rel="noopener noreferrer">Add filters for created_at and updated_at to GET Transactions API</a>
+- <a href="https://feedback.lunchmoney.app/developer-api/p/account-metadata-hash" target="_blank" rel="noopener noreferrer">Custom Metadata on Manual Accounts</a>
+
+This guide covers what changed from v1 to v2 and how to update your integration. For a general introduction to v2 concepts — authentication, response shapes, naming conventions, error handling, and hydration — see the [v2 API Overview](/v2/overview).
+
+## Getting Started
+
+Before you begin:
+
+1. Review the [v2 API Overview](/v2/overview) for general concepts
+2. Test your migration in a development environment
+3. Keep your v1 integration working as a fallback until migration is complete
+
+> [!TIP] Migration Strategy
+> Start with read operations first, then gradually migrate write operations. This allows you to test v2 responses while still relying on v1 for writes during the transition.
+
+## Base URL Changes
+
+The base URL for all API requests changes from:
+
+```
+https://api.lunchmoney.dev/v1/
+```
+
+to:
+
+```
+https://api.lunchmoney.dev/v2
+```
+
+## General Changes
+
+### Error Handling
+
+> [!WARNING] Breaking Change
+> The v1 API often returns `200 OK` even when the request fails — the error is in the response body. Update your error handling to check HTTP status codes instead of inspecting 2XX response bodies.
+
+The v2 API returns consistent 4XX status codes for errors and validates all requests strictly, including query parameters and request body properties that v1 would silently ignore. See [Error Responses](/v2/overview#error-responses) in the v2 API Overview for the full status code table and error body format.
+
+### Response Codes
+
+Two status code changes affect all endpoints:
+
+- **POST requests** now return `201 Created` (was `200 OK`)
+- **DELETE requests** now return `204 No Content` with no response body (was `200 OK` with `true`)
+
+See [Response Shapes](/v2/overview#response-shapes) in the v2 API Overview for the complete table.
+
+### Updating Objects
+
+> [!WARNING] Property Replacement Behavior
+> Complex properties — objects and arrays — are **replaced entirely** by what you send in the PUT body. To add a tag without removing existing ones, fetch the object first, update the array, then PUT the full array back.
+
+The v2 PUT pattern (GET → modify → PUT the full object) and all other PUT rules are covered in [Updating Objects](/v2/overview#updating-objects-put) in the v2 API Overview.
+
+### Property Naming Conventions
+
+Property names are standardized across all v2 objects. The specific renames are listed in the endpoint sections below. See [Naming Conventions](/v2/overview#naming-conventions) in the v2 API Overview for the general rules.
+
+One change worth noting: all `id` fields are now explicitly `integer` type (not `number`). This should not affect most apps.
+
+## Object and Endpoint Specific Changes
+
+### User Object
+
+#### Property Renames
+
+:::tabs
+@tab v1
+```javascript
+{
+  "user_id": 123,
+  "user_name": "John Doe",
+  "user_email": "john@example.com"
+}
+```
+
+@tab v2
+```javascript
+{
+  "id": 123,
+  "name": "John Doe",
+  "email": "john@example.com"
+}
+```
+:::
+
+#### New Properties
+
+- `debits_as_negative`: A user preference shown in the Lunch Money app. This no longer changes how transaction amounts are represented in the v2 API, but apps may use this setting to display amounts and balances in the way the user prefers. See the [Amounts & Balances guide](/v2/amounts-and-balances) for details.
+
+<a href="./changelog-visual#user-object-row" target="_blank" rel="noopener noreferrer">View v1/v2 differences</a>
+
+<a href="/v2/docs#model/userObject">View v2 User Object Docs</a>
+
+
+**Migration Tips**: 
+- Update all references to `user_id`, `user_name`, and `user_email` in your code to use the new property names.
+- Do not use the user's `debits_as_negative` setting to interpret v2 transaction amounts. In the v2 API, positive `amount` values are always debits and negative `amount` values are always credits.
+
+### Categories
+
+#### Endpoint Changes
+
+#### Creating Categories
+
+v1 had separate endpoints for categories and category groups. v2 uses a single endpoint:
+
+:::tabs
+@tab v1 - Create category
+```javascript
+POST /v1/categories
+{ "name": "Groceries", ... }
+```
+
+@tab v1 - Create category group
+```javascript
+POST /v1/categories/group
+{ "name": "Food & Drink", "category_ids": [...], ... }
+```
+
+@tab v2 - Single endpoint
+```javascript
+// Regular category
+POST /v2/categories
+{ "name": "Groceries", ... }
+
+// Category group
+POST /v2/categories
+{ "name": "Food & Drink", "is_group": true, "children": [...] }
+```
+:::
+
+#### Adding to Category Groups
+
+v1 had a unique endpoint for adding children to an existing category group.  
+v2 allows children to be modified via the `PUT /categories` endpoint.
+
+:::tabs
+@tab v1
+```javascript
+POST /v1/categories/group/:group_id/add
+{ "category_ids": [1, 2, 3] }
+```
+
+@tab v2
+```javascript
+PUT /v2/categories/:id
+{ "children": [1, 2, 3] }  // Replaces all children
+```
+:::
+
+#### Deleting Categories
+When attempting to delete a category, both the v1 and v2 APIs will return a `dependents` object if other Lunch Money elements (ie: transactions, rules, etc) depend on the category. Both versions also provide a way to force delete the category when this happens but the syntax is slightly different:
+
+:::tabs
+@tab v1
+```javascript
+DELETE /v1/categories/:id/force
+```
+
+@tab v2
+```javascript
+DELETE /v2/categories/:id?force=true
+```
+:::
+
+#### Response Changes
+
+- `POST /categories` now returns the complete category object
+  -  (v1 returns just the id, ie: `{ "category_id": 123 }`)
+- `PUT /categories/:id` returns the complete updated category object (not just `true`)
+- `DELETE /categories/:id` returns `204 No Content` (not `true`)
+
+#### Object Property Changes
+
+- `children` property of a category group is never `null` - it's an empty array `[]` for groups with no children
+  - There is no `children` property in (non group) categories
+- `group_category_name` has been removed
+- `group_name` is now present on all grouped categories (not just in certain responses)
+- `collapsed` is now present on all category objects. When set to `true` on a category group it will appear collapsed in the Web UI.
+
+<a href="./changelog-visual#category-object-row" target="_blank" rel="noopener noreferrer">View v1/v2 differences</a><br>
+<a href="/v2/docs#model/categoryObject">View v2 Category Object Docs</a>
+
+
+
+##### Query Parameters
+
+Categories in the v2 nested response are ordered by the `order` property. When `order` is not set on a category, it falls back to alphabetical ordering.
+
+:::tabs
+@tab v1
+```javascript
+GET /v1/categories?format=nested  // or "flattened" - default: flattened
+```
+
+@tab v2
+```javascript
+GET /v2/categories  // Default: nested ordered list
+GET /v2/categories?format=flattened  // All categories including duplicates
+GET /v2/categories?is_group=false  // Only assignable categories (no groups)
+GET /v2/categories?is_group=true   // Only category groups
+```
+:::
+
+
+
+**Migration**:
+- Add the `format` query parameter to GET /v2/categories requests as needed, the default has changed 
+- Update category and category group creation logic to use a single endpoint with `is_group` property
+- Update group management to use `PUT` with `children` array
+- Handle the new query parameters for filtering categories
+- Update code that checks `children === null` to check for empty array instead
+- Update code to use created or modified categories returned directly from `POST` and `PUT` requests.
+
+### Tags
+
+#### New Properties
+
+The tag object now includes:
+- `created_at`
+- `updated_at`
+- `archived_at`
+
+<a href="./changelog-visual#tags-object-row" target="_blank" rel="noopener noreferrer">View v1/v2 differences</a><br>
+<a href="/v2/docs#model/tagObject">View v2 Tag Object Docs</a>
+
+#### New Endpoints
+
+v2 adds full CRUD operations for tags:
+
+```javascript
+// Get single tag
+GET /v2/tags/:id
+
+// Create tag
+POST /v2/tags
+{ "name": "Work Expense", ... }
+
+// Update tag
+PUT /v2/tags/:id
+{ "name": "Business Expense", ... }
+
+// Delete tag
+DELETE /v2/tags/:id
+```
+
+#### List Ordering
+
+`GET /tags` now returns tags in alphabetical order (matching the GUI).
+
+**Migration**: Take advantage of the new tag management endpoints if you need to create or modify tags programmatically.
+### Transactions
+The transaction object has changed significantly in v2. A transaction has properties that reference other objects in Lunch Money such as categories, accounts, and tags. In v1 certain details for these related objects were "hydrated". In the context of RESTful APIs, "hydration" generally refers to populating an object with all its data. In the Lunch Money APIs, hydration generally relates to providing some details of associated objects that are also referred to by their IDs in the response body.
+
+
+> [!NOTE] Breaking Change: Dehydrated Responses
+> To optimize the responsiveness of the v2 Lunch Money APIs, the transaction object will no longer be hydrated. Categories, accounts, and tags are now returned as IDs only.  Details of these objects can be retrieved by calling the appropriate endpoint using the supplied ID.   Developers are encouraged to maintain a local cache of these objects to reduce the number of API calls.
+
+:::tabs
+@tab v1 - Hydrated
+```javascript
+{
+  "id": 123,
+  "category_id": 456,
+  "category_name": "Groceries",  // ❌ Not in v2
+  "category_group_id": 789,       // ❌ Not in v2
+  "category_group_name": "Food",  // ❌ Not in v2
+  "is_income": false,             // ❌ Not in v2
+  "tags": [                       // ❌ Not in v2
+    { "id": 1, "name": "Work" }
+  ],
+  "asset_name": "Checking",       // ❌ Not in v2
+  "plaid_account_name": "...",    // ❌ Not in v2
+  ...
+}
+```
+
+@tab v2 - IDs only
+```javascript
+{
+  "id": 123,
+  "category_id": 456,             // ✅ Still here
+  "tag_ids": [1, 2],              // ✅ Array of IDs
+  "manual_account_id": 789,       // ✅ Renamed from asset_id
+  "plaid_account_id": 123,        // ✅ Still here
+  ...
+}
+```
+:::
+
+To get full details, fetch the related objects:
+
+```javascript
+// Get category details
+GET /v2/categories/456
+
+// Get account details
+GET /v2/manual_accounts/789
+// OR
+GET /v2/plaid_accounts/123
+
+// Get tag details
+GET /v2/tags/1
+```
+
+**Migration Strategy**: 
+- Maintain a local cache of categories, accounts, and tags
+- Update your code to use IDs and fetch related objects separately when needed
+- Consider batching requests or using the bulk endpoints to reduce API calls
+
+#### Removed Properties
+
+The following properties found in the hydrated v1 Transaction Object are no longer present in the v2 Transaction object
+
+These category-related properties are no longer included (get from category object):
+- `category_name`
+- `category_group_id`
+- `category_group_name`
+- `is_income`
+- `exclude_from_budget`
+- `exclude_from_totals`
+- `group_category_name`
+
+These account-related properties are no longer included (get from account object):
+- `asset_institution_name`
+- `asset_name`
+- `asset_display_name`
+- `asset_status`
+- `plaid_account_name`
+- `plaid_account_mask`
+- `institution_name`
+- `plaid_account_display_name`
+
+#### Renamed Properties
+The following properties have been renamed or refactored in the v2 Transaction object
+
+- `asset_id` → `manual_account_id` 
+- `tags` (array of objects) → `tag_ids` (array of tag id integers)
+- `has_children` → `is_split_parent`
+- `parent_id` →  `split_parent_id`
+- `is_group` →  `is_group_parent`
+- `group_id` →  `group_parent_id`
+- `display_name` → removed (use `payee` directly)
+- `display_notes` → removed (use `notes` directly)
+
+These recurring-related properties have changed:
+- `recurring_payee`, `recurring_description`, etc. are now in an `overrides` object
+- Check the transaction's `recurring_id` and fetch from `/v2/recurring/:id` for details
+
+
+<a href="./changelog-visual#transaction-object-row" target="_blank" rel="noopener noreferrer">View v1/v2 differences</a><br>
+<a href="/v2/docs#model/transactionObject">View v2 Transaction Object Docs</a>
+
+
+#### Transaction Amounts
+The `debit_as_negative` property has been removed as an optional query parameter and request body property in the `/transactions` endpoints. In the v2 API, positive `amount` values always indicate debit transactions and negative `amount` values always indicate credit transactions, regardless of the user's `debits_as_negative` setting in the Lunch Money app.
+
+:::tabs
+@tab v1
+```javascript
+GET /v1/transactions?debit_as_negative=false  // Query parameter
+```
+
+@tab v2
+```javascript
+GET /v2/transactions
+// Positive amount values indicate debit transactions
+// Negative amount values indicate credit transactions
+```
+:::
+
+> [!WARNING] Behavior Change
+> In the v1 API the optional `debit_as_negative` query parameter could change how transaction amounts were represented. In the v2 API, transaction amount signs are fixed: positive values are debits and negative values are credits. Existing applications that assume positive values are credits need to be updated.
+
+See the [Amounts & Balances guide](/v2/amounts-and-balances) for the full sign convention and how `to_base` works for multi-currency accounts.
+
+
+> [!TIP] Migration Tip
+> Remove `debit_as_negative` query parameters and update your code to interpret positive transaction amounts as debits and negative amounts as credits.
+
+#### Status Values
+
+:::tabs
+@tab v1
+```javascript
+"status": "cleared" | "uncleared" | "pending" | "recurring" | "recurring_suggested"
+```
+
+@tab v2
+```javascript
+"status": "reviewed" | "unreviewed" | "deleted_pending"
+```
+:::
+
+**Migration**: Update status checks:
+- `"cleared"` → `"reviewed"`
+- `"uncleared"` → `"unreviewed"`
+- Transactions with `is_pending: true` always have status `"unreviewed"`
+- Update any code logic that checks if `status` is `pending` to use `is_pending` instead
+
+#### Split and Grouped Transactions
+
+**Split Transactions**:
+- Parents of split transactions (`is_parent: true`) are not returned by default in `GET /transactions`
+- Split transactions include `split_parent_id` pointing to the parent
+- Use `GET /transactions/:id` to get parent with full `children` array
+- Use `GET /transactions` with query param `include_split_parents=true` to include parents in list
+
+**Grouped Transactions**:
+- Transactions that have been grouped are not returned by default
+- Only the group transaction (`is_group: true`) is returned
+- Use `GET /transactions/:id` to get details of grouped transactions in the transaction group's `children` array.
+
+
+**Migration**: Update code that processes split or grouped transactions to use the details endpoint when info is needed about split parent transactions, or transactions that are now part of a grouped transaction.
+
+#### Query Parameters
+
+:::tabs
+@tab v1
+```javascript
+GET /v1/transactions?pending=true&debit_as_negative=false
+```
+
+@tab v2
+```javascript
+GET /v2/transactions?include_pending=true
+// debit_as_negative removed
+// Positive amount values indicate debit transactions
+// Negative amount values indicate credit transactions
+// New optional parameters:
+// ?include_metadata=true      // Include plaid_metadata, custom_metadata
+// ?include_files=true         // Include file attachments
+// ?include_children=true      // Include children for split/grouped
+// ?include_split_parents=true // Include parent transactions
+// ?created_since=2024-01-01   // Filter by creation timestamp (date or datetime)
+// ?updated_since=2024-01-01T12:00:00Z  // Filter by update timestamp (date or datetime)
+```
+:::
+
+**Migration**: Update query parameter names on `GET /transaction`
+- remove `debit_as_negative`
+- add new `include_XXX` params to get additional info in the returned objects
+- use `created_since` and `updated_since` to filter transactions by creation or update timestamps (accepts date YYYY-MM-DD or ISO 8601 datetime format)
+
+
+#### Creating Transactions
+
+Request body changes:
+
+:::tabs
+@tab v1
+```javascript
+POST /v1/transactions
+{
+  "transactions": [...],
+  "debit_as_negative": false,  // ❌ Removed in v2
+  ...
+}
+```
+
+@tab v2
+```javascript
+POST /v2/transactions
+{
+  "transactions": [
+    {
+      "asset_id": 123,      // ❌ Renamed
+      "manual_account_id": 123,  // ✅ New name
+      "tags": ["Work"],     // ❌ Can't create tags on the fly
+      "tag_ids": [1, 2]     // ✅ Must use existing tag IDs
+    }
+  ]
+}
+```
+:::
+
+Response body changes (specific to duplicate detection):
+
+:::tabs
+@tab v1 - Success
+```javascript
+{
+  "ids": [new_transaction1.id, ...],
+}
+```
+
+@tab v1 - Duplicate
+```javascript
+{
+  "error": [
+    "Key (user_external_id, asset_id, account_id)=(123457891, 178181, 66938) already exists."
+  ]
+}
+```
+
+@tab v2 - Success
+```javascript
+// New transactions ARE inserted, even if some are duplicates
+{
+  "transactions": [
+    {
+      "id": 8
+      // rest of full transaction object
+    },
+    {
+      "id": 9,
+      // rest of full transaction object
+    }
+  ],
+  "skipped_duplicates": [
+    {
+      "reason": "duplicate_external_id",
+      "request_transactions_index": 1,
+      "existing_transaction_id": 2, // id of the existing match
+      "request_transaction": {      // from the request body
+        "date": "2025-06-20",
+        "amount": "250.0000",
+        "payee": "Fidelity",
+        "manual_account_id": 1,
+        "external_id": "12345",
+      }
+    }
+  ]
+}
+```
+:::
+
+> [!WARNING] Important Changes
+> - `asset_id` → `manual_account_id`
+> - `tags` array (could include strings to create tags) → `tag_ids` array (only existing IDs)
+> - `plaid_account_id` can now be set when creating transactions (if account allows modifications)
+> - `debit_as_negative` removed - positive amounts are debits and negative amounts are credits
+> - Duplicated transactions (due to `external_id` conflict, or matching `date`, `amount` and account when `skip_duplicates: true` is in the request body), no longer cause the entire request to fail. Non-duplicates are inserted, and duplicates are reported
+
+> [!TIP] Migration Steps
+> - Ensure that amounts are properly signed for inserted transactions. Regardless of the value of the users `debits_as_negative` property always use positive numbers for debits and negative numbers for credits.
+> - When creating transactions with tags, create new tags first using `POST /tags` before assigning them
+> - Update changed property names in request bodies 
+> - Modify handling of success responses to leverage the full objects for inserted transactions
+> - Check success response for `skipped_duplicates`
+
+
+#### Updating Transactions
+
+:::tabs
+@tab v1
+```javascript
+PUT /v1/transactions/:id
+{
+  "transaction": { ... },
+  "split": [...],              // ❌ Moved to separate endpoint
+  "debit_as_negative": false,  // ❌ Removed
+  "skip_balance_update": true  // ❌ Renamed
+}
+```
+
+@tab v2 - Single transaction
+```javascript
+PUT /v2/transactions/:id?update_balance=false  // Query parameter
+{
+  // Just the transaction properties to update OR
+  // A full transaction object with at least one updatable property modified
+}
+```
+
+@tab v2 - Bulk update (new)
+```javascript
+PUT /v2/transactions
+{
+  "transactions": [...]  
+  // Array of full or partial transaction objects to update
+  // Each object MUST include the id of the existing transaction to update
+  // The rest of the object should be at least one property to update
+}
+```
+:::
+
+**Migration**: 
+- Take advantage of new bulk update endpoint where appropriate
+- Migrate code to split transactions to the new endpoint described below
+
+#### Splitting and Grouping Transactions
+These endpoints have been modified to follow the standard pattern of using `POST` to create something and `PUT` to modify something, and `DELETE` to remove something.
+
+**Splitting Transactions**:
+
+:::tabs
+@tab v1
+```javascript
+PUT /v1/transactions/:id
+{ "split": [...] }
+```
+
+@tab v2
+```javascript
+POST /v2/transactions/split/:id
+{ "child_transactions": [
+    // objects with at least "amount" and "payee" fields
+] }
+```
+:::
+
+> [!NOTE] New Capability
+> Child transactions in `POST /transactions/split/{id}` now support `tag_ids`.
+
+**Unsplit Transactions**:
+
+:::tabs
+@tab v1
+```javascript
+POST /v1/transactions/unsplit
+{ "parent_ids": [...] }
+```
+
+@tab v2
+```javascript
+DELETE /v2/transactions/split/:parent_id
+```
+:::
+
+<a href="/v2/docs#tag/transactions-split">View v2 Split Transaction Endpoint Docs</a><br>
+
+**Grouping Transactions**:
+
+:::tabs
+@tab v1
+```javascript
+POST /v1/transactions/group
+{ 
+    "transactions": [id1, id2, ...],
+    // other properties, ie: date, payee
+}
+```
+
+@tab v2
+```javascript
+POST /v2/transactions/group
+{ 
+    "ids": [id1, id2,...] 
+    // other properties remain the same    
+}
+```
+:::
+
+**Ungroup Transactions**:
+
+:::tabs
+@tab v1
+```javascript
+DELETE /v1/transactions/group/:id
+// Returns 200 with a transactions array of ids that were ungrouped
+```
+
+@tab v2
+```javascript
+DELETE /v2/transactions/group/:id
+// Returns 204 No Content
+```
+:::
+
+<a href="/v2/docs#tag/transactions-group">View v2 Group Transactions Endpoint Docs</a><br>
+
+**Important Changes**:
+- New method and endpoint to split transactions which returns the original transaction with children
+- Mew method and endpoint to unsplit transactions which returns a 204 No Content
+- `ids` property replaces `transactions` on the `POST /transactions/group` endpoint
+- New method and endpoint to ungroup transactions which returns a 204 No Content
+
+**Migration**: 
+- Move split and group logic to the new endpoints as needed
+
+#### Deleting Transactions
+> [!NOTE] New Feature
+> It is now possible to delete transactions via the API!
+
+:::tabs
+@tab v1
+```javascript
+// No delete endpoint available
+```
+
+@tab v2 - Single
+```javascript
+DELETE /v2/transactions/:id        // Single transaction
+```
+
+@tab v2 - Bulk
+```javascript
+DELETE /v2/transactions            // Bulk delete
+{ "ids": [1, 2, 3] }
+```
+:::
+
+<a href="/v2/docs#tag/transactions/DELETE/transactions/{id}">View v2 Delete Transactions Endpoint Docs</a><br>
+<a href="/v2/docs#tag/transactions-bulk/DELETE/transactions">View v2 Bulk Delete Transactions Endpoint Docs</a><br>
+
+
+**Migration**: Update code that may have been working around the lack of delete endpoints.
+
+> [!WARNING] Use With Caution!
+> Deletions are permanent. Ensure apps that use these endpoints are very well tested before using on real user data.
+
+
+#### Transaction Attachments (New)
+
+v2 introduces the ability to view, create and delete file attachments to transactions
+
+```javascript
+// Upload attachment
+POST /v2/transactions/:transaction_id/attachments
+// multipart/form-data with file and optional notes
+
+// Get attachment details
+GET /v2/transactions/attachments/:file_id
+
+// Get download URL
+GET /v2/transactions/attachments/:file_id/url
+
+// Delete attachment
+DELETE /v2/transactions/attachments/:file_id
+```
+<a href="/v2/docs#tag/transactions-files">View v2 Transaction Attachment Endpoint Docs</a><br>
+
+### Recurring Items
+A new `GET v2/recurring_items/{id} endpoint to get a single recurring item has been added.
+
+<a href="/v2/docs#tag/recurring_items">View v2 Recurring Endpoint Docs</a><br>
+
+#### Object Structure Changes
+
+> [!NOTE] Major Reorganization
+> The recurring object's properties are now grouped into three nested objects: `transaction_criteria` (scheduling and amount details), `overrides` (per-occurrence customizations), and `matches` (query results). Previously these were all flat top-level properties.
+
+:::tabs
+@tab v1
+```javascript
+{
+  "id": 123,
+  "start_date": "2024-01-01",
+  "end_date": null,
+  "billing_date": "2024-01-15",
+  "payee": "Netflix",
+  "amount": "15.99",
+  "category_id": 456,
+  "category_group_id": 789,    // ❌ Removed
+  "is_income": false,          // ❌ Removed (get from category)
+  "exclude_from_totals": false, // ❌ Removed (get from category)
+  "granularity": "month",
+  "quantity": 1,
+  "occurrences": { ... },
+  "transactions_within_range": [...],
+  "missing_dates_within_range": [...],
+  "date": "2024-06-04"
+}
+```
+
+@tab v2
+```javascript
+{
+  "id": 123,
+  "description": "Netflix subscription",
+  "source": "manual",
+  "status": "reviewed",  // ✅ New: "reviewed" or "suggested"
+  "transaction_criteria": {
+    "start_date": "2024-01-01",  // ✅ Moved here
+    "end_date": null,             // ✅ Moved here
+    "anchor_date": "2024-01-15",  // ✅ Renamed from billing_date
+    "payee": "Netflix",            // ✅ Moved here
+    "amount": "15.99",             // ✅ Moved here
+    "currency": "usd",
+    "granularity": "month",        // ✅ Moved here
+    "quantity": 1,                 // ✅ Moved here
+    "manual_account_id": 123,
+    "plaid_account_id": null
+  },
+  "overrides": {
+    "payee": "Netflix Subscription",  // ✅ Moved here
+    "notes": "Monthly subscription",
+    "category_id": 456                // ✅ Moved here
+  },
+  "matches": {
+    "request_start_date": "2024-06-01",  // ✅ Renamed from date
+    "request_end_date": "2024-06-30",    // ✅ New
+    "expected_occurrence_dates": [...],   // ✅ Renamed from occurrences
+    "found_transactions": [               // ✅ Renamed from transactions_within_range
+      { "date": "2024-06-15", "transaction_id": 789 }
+    ],
+    "missing_transaction_dates": [...]    // ✅ Renamed from missing_dates_within_range
+  }
+}
+```
+:::
+
+<a href="./changelog-visual#recurring-object-row" target="_blank" rel="noopener noreferrer">View v1/v2 Recurring Object differences</a><br>
+<a href="/v2/docs#model/recurringObject">View v2 Recurring Object Docs</a>
+
+
+#### Query Parameters
+
+:::tabs
+@tab v1
+```javascript
+GET /v1/recurring_items?start_date=2024-06-01
+```
+
+@tab v2
+```javascript
+GET /v2/recurring?start_date=2024-06-01&end_date=2024-06-30  // Both required if using dates
+GET /v2/recurring?include_suggested=true  // Include suggested recurring items
+```
+:::
+
+**Migration**: 
+- Update endpoint path
+- Restructure code to access properties in their new locations
+- Update property names (`billing_date` → `transaction_criteria.anchor_date`)
+- Use both `start_date` and `end_date` when specifying a range
+
+### Manual Accounts (formerly Assets)
+The /assets endpoint was renamed to /manual_accounts to align with language used in the web client.
+
+#### Endpoint Rename
+
+:::tabs
+@tab v1
+```javascript
+GET /v1/assets
+POST /v1/assets
+PUT /v1/assets/:id
+```
+
+@tab v2
+```javascript
+GET /v2/manual_accounts
+POST /v2/manual_accounts
+PUT /v2/manual_accounts/:id
+GET /v2/manual_accounts/:id    // ✅ New: Get single account
+DELETE /v2/manual_accounts/:id // ✅ New: Delete account
+```
+:::
+
+<a href="/v2/docs#tag/manual_accounts">View v2 Manual Accounts Endpoint Docs</a><br>
+
+#### Property Renames
+
+```javascript
+// v1 → v2
+"type_name" → "type"
+"subtype_name" → "subtype"
+"exclude_transactions" → "exclude_from_transactions"
+```
+
+> [!NOTE] Type Name Change
+> Accounts with `type_name: "depository"` now return `type: "cash"`.
+
+#### New Properties
+
+- `updated_at`
+- `external_id` (API-only, can be set/updated via API)
+- `custom_metadata` (API-only, any valid JSON object < 4MB)
+
+<a href="./changelog-visual#manual-account-object-row" target="_blank" rel="noopener noreferrer">View v1/v2 Manual Account Object differences</a><br>
+<a href="/v2/docs#model/manualAccountObject">View v2 Manual Account Object Docs</a>
+
+**Migration**: 
+- Update all endpoint paths from `/assets` to `/manual_accounts`
+- Update property names in your code
+- Handle the `depository` → `cash` type change
+- Take advantage of new endpoints for single account and delete operations
+
+### Plaid Accounts
+
+#### New Endpoints
+
+```javascript
+// v1 - Only list endpoint
+GET /v1/plaid_accounts
+
+// v2 - Added single account endpoint
+GET /v2/plaid_accounts
+GET /v2/plaid_accounts/:id
+```
+<a href="/v2/docs#tag/plaid_accounts">View v2 Plaid Accounts Endpoint Docs</a><br>
+
+#### New Response Properties
+
+- `allow_transaction_modification`: Boolean indicating if transactions can be modified (enabled by default)
+
+<a href="./changelog-visual#plaid-account-object-row" target="_blank" rel="noopener noreferrer">View v1/v2 Plaid Account Object differences</a><br>
+<a href="/v2/docs#model/plaidAccountObject">View v2 Plaid Account Object Docs</a>
+
+
+#### Fetch Endpoint Changes
+
+:::tabs
+@tab v1
+```ts
+POST /v1/plaid_accounts/fetch
+// Returns: true
+```
+
+@tab v2
+```ts
+POST /v2/plaid_accounts/fetch
+// Returns: { "plaid_accounts": [...] }  // List of accounts that were fetched
+```
+:::
+
+**Migration**: Update fetch response handling to expect an object with `plaid_accounts` array instead of `true`.
+
+### Crypto Balances
+
+The v2 API adds crypto endpoints that support the full lifecycle of manual crypto balances. It also adds endpoints for viewing and extending the list of supported manual cryptocurrencies.
+
+The v2 API also provides new endpoints for reading and refreshing synced crypto balances. Synced crypto account linking and management are supported in the Lunch Money Web app only.
+
+:::tabs
+@tab v1
+```ts
+GET /v1/crypto //manual balances only
+```
+
+@tab v2
+```ts
+GET /v2/cryptocurrencies
+POST /v2/cryptocurrencies
+GET /v2/crypto/manual
+GET /v2/crypto/manual/:id
+GET /v2/crypto/synced
+GET /v2/crypto/synced/:id    // Returns one synced crypto account with nested balances
+GET /v2/crypto/synced/:id/:symbol
+POST /v2/crypto/synced/:id/refresh
+POST /v2/crypto/manual
+PUT /v2/crypto/manual/:id
+DELETE /v2/crypto/manual/:id
+```
+:::
+
+
+<a href="/v2/docs#tag/crypto-manual">View v2 Manual Crypto Docs</a><br>
+<a href="/v2/docs#tag/crypto-synced">View v2 Synced Crypto Docs</a><br>
+<a href="./changelog-visual#crypto-object-row" target="_blank" rel="noopener noreferrer">View v1/v2 Crypto Object differences</a>
+
+**Migration**:
+- Replace `GET /v1/crypto` consumers with one of:
+  - `GET /v2/crypto/manual` for manual-only balances
+  - `GET /v2/crypto/synced` for synced-only balances
+- If your app lets users add manual crypto balances for unsupported symbols, first call `GET /v2/cryptocurrencies` to inspect the supported catalog, then `POST /v2/cryptocurrencies` with a CoinGecko coin-page URL when a symbol is missing
+- Treat `source` as the contract-level differentiator (`manual` vs `synced`)
+- For synced account-specific reads, update handlers to expect a single synced crypto account object with nested `balances` on `GET /v2/crypto/synced/:id`
+- Use `GET /v2/crypto/synced/:id/:symbol` when you need one balance from a synced crypto account
+- For manual deletes, handle `422 Unprocessable Content` when `keep_history` is not explicitly provided and history exists
+
+### Summary Endpoint
+A new `v2/summary` endpoint replaces the `v1/budgets` endpoint.
+
+This endpoint significantly refactors the response and aligns with the recently released v2 Budgets feature.
+
+> [!NOTE] `include_occurrences=true`
+> When `include_occurrences` is set to `true`, each returned category includes an `occurrences` array.
+> - For aligned ranges, the array includes one occurrence per budget period in range.
+> - For non-aligned ranges, the array includes only budget periods fully contained in range.
+> - You can inspect `start_date` and `end_date` in occurrence objects to choose a fully aligned date range for subsequent requests.
+
+<a href="/v2/docs#tag/summary">View v2 Summary Endpoint Docs</a><br>
+<a href="/v2/docs#model/alignedSummaryResponseObject">View v2 Summary Object Docs</a><br>
+
+### budgets endpoints
+
+- **`GET /budgets/settings`** has been added <a href="/v2/docs#tag/budgets/GET/budgets/settings">View Docs</a>
+- **`PUT /budgets`** has been added <a href="/v2/docs#tag/budgets/PUT/budgets">View Docs</a>
+- **`DELETE /budgets`** has been added <a href="/v2/docs#tag/budgets/DELETE/budgets">View Docs</a>
+
+### balance_history endpoints (New)
+
+- **`GET /balance_history`** has been added <a href="/v2/docs#tag/balance_history">View Docs</a>
+- **`GET /balance_history/{account_type}/{account_id}`** has been added <a href="/v2/docs#tag/balance_history">View Docs</a>
+- **`GET /balance_history/crypto_synced/{account_id}/{symbol}`** has been added <a href="/v2/docs#tag/balance_history">View Docs</a>
+- **`PUT /balance_history/{account_type}/{account_id}`** has been added <a href="/v2/docs#tag/balance_history">View Docs</a>
+- **`PUT /balance_history/crypto_synced/{account_id}/{symbol}`** has been added <a href="/v2/docs#tag/balance_history">View Docs</a>
+- **`DELETE /balance_history/{account_type}/{account_id}`** has been added <a href="/v2/docs#tag/balance_history">View Docs</a>
+- **`DELETE /balance_history/crypto_synced/{account_id}/{symbol}`** has been added <a href="/v2/docs#tag/balance_history">View Docs</a>
+- **`DELETE /balance_history/entries/{id}`** has been added <a href="/v2/docs#tag/balance_history">View Docs</a>
+- **`PUT /balance_history/deleted/{account_id}/details`** has been added <a href="/v2/docs#tag/balance_history">View Docs</a>
+
+### Common Migration Patterns
+
+#### Pattern 1: Getting object details for non hydrated responses
+
+:::tabs
+@tab v1 - Hydrated
+```javascript
+const transaction = await getTransaction(123);
+console.log(transaction.category_name);  // Direct access
+```
+
+@tab v2 - Fetch separately
+```javascript
+const transaction = await getTransaction(123);
+const category = await getCategory(transaction.category_id);
+console.log(category.name);  // Access from category object
+```
+
+@tab v2 - With caching
+```javascript
+// Better: Cache categories
+const categoryCache = new Map();
+async function getCategoryName(id) {
+  if (!categoryCache.has(id)) {
+    const cat = await getCategory(id);
+    categoryCache.set(id, cat);
+  }
+  return categoryCache.get(id).name;
+}
+```
+:::
+
+#### Pattern 2: Handling Response Codes
+
+:::tabs
+@tab v1
+```javascript
+// All success responses were 200 OK
+if (response.status === 200) {
+  const data = response.data;  // Might be true, an ID, an error message, or a complex response object
+}
+```
+
+@tab v2
+```javascript
+// Proper HTTP status codes
+if (response.status === 201) {
+  // POST - created object in response.body
+  const created = response.body;
+} else if (response.status === 200) {
+  // GET - requested items are returned
+  // PUT - updated object in response.body
+  const updated = response.body;
+} else if (response.status === 204) {
+  // DELETE - no response body
+  // Success!
+}
+```
+:::
+
+#### Pattern 3: Error Handling
+
+:::tabs
+@tab v1
+```javascript
+// Inconsistent error formats
+try {
+  // Some errors returned as 200 with { error: "message" }
+  // Some errors returned as 200 with { errors: ["message"] }
+  // Some errors returned as 404
+} catch (e) {
+  // Handle inconsistently
+}
+```
+
+@tab v2
+```javascript
+// Consistent error format
+try {
+  const response = await api.post('/transactions', data);
+} catch (error) {
+  if (error.response.status === 400) {
+    const { message, errors } = error.response.body;
+    errors.forEach(err => {
+      console.error(err.errMsg);
+    });
+  }
+}
+```
+:::
+
+#### Pattern 4: Creating New Tags with New Transactions
+
+:::tabs
+@tab v1
+```javascript
+// Create tags on the fly
+POST /v1/transactions
+{
+  "transactions": [{
+    "tags": ["New Tag"]  // Creates tag automatically
+  }]
+}
+```
+
+@tab v2
+```javascript
+// Step 1: Create tag
+const tag = await POST /v2/tags { name: "New Tag" };
+
+// Step 2: Use tag ID
+POST /v2/transactions
+{
+  "transactions": [{
+    "tag_ids": [tag.id]
+  }]
+}
+```
+:::
+
+### Testing Your Migration
+
+1. **Start with Read Operations**: Update your code to read from v2 endpoints first
+2. **Handle Dehydration**: Ensure your code can work with IDs instead of hydrated objects
+3. **Update Write Operations**: Migrate create/update/delete operations
+4. **Test Edge Cases**: 
+   - Split transactions
+   - Grouped transactions
+   - Transactions with recurring items
+   - Category groups with children
+5. **Verify Error Handling**: Test various error scenarios to ensure proper handling
+6. **Add New Capabilities**: Take advantage of new endpoints to fully manage Transactions, Tags, and Manual Accounts and more.
+
+### Need Help?
+
+If you run into issues during migration:
+
+- Review the [v2 API documentation](../v2/)
+- Review the [v2 API Overview](/v2/overview) for general concepts
+- <a href="https://lunchmoney.app/discord" target="_blank" rel="noopener noreferrer">Join the Lunch Money community on Discord</a> and send a question in the <a href="https://discord.com/channels/842337014556262411/1134594318414389258" target="_blank" rel="noopener noreferrer">Developer API Channel</a>.
+- [Email our developer advocate](mailto:jp@lunchmoney.app).
+
+We're here to help make your migration as smooth as possible!