Feature Request: Add transaction update and delete endpoints to the public API

[SGiersch]

Feature Request: Add transaction update and delete endpoints to the public API

Description

The public Budget API currently provides endpoints for reading transactions and creating new transactions, but there is no public API endpoint for updating or deleting an existing transaction.

This makes it difficult for external clients, mobile applications and automation tools to provide a complete transaction workflow.

I would like to propose adding official API endpoints for updating and deleting transactions, while keeping all existing Budget business rules and permission checks in place.

The goal is not to expose internal web endpoints, but to provide a stable, documented API specifically intended for external clients.

Proposed API

Update a transaction

I suggest using:

PATCH /ocs/v2.php/apps/budget/api/v1/transactions/{id}

PATCH would allow clients to update only the fields that have changed.

For example:

PATCH /ocs/v2.php/apps/budget/api/v1/transactions/123
Content-Type: application/json

{
  "date": "2026-09-28",
  "amount": 42.50,
  "description": "Supermarket",
  "vendor": "Example Market",
  "category_id": 15,
  "notes": "Updated transaction"
}

The response should return the updated transaction in the same representation used by the existing transaction API.

Delete a transaction

I suggest:

DELETE /ocs/v2.php/apps/budget/api/v1/transactions/{id}

For example:

DELETE /ocs/v2.php/apps/budget/api/v1/transactions/123

A successful deletion could return the deleted transaction or an appropriate OCS success response.

Why PATCH instead of PUT?

PATCH seems appropriate because clients will often change only one or two properties of a transaction.

For example, a user may only want to:

• change the category
• correct the date
• correct the amount
• change the description
• change the vendor
• add or modify notes

The client should not have to send the complete transaction object just to change one property.

Important business rules / edge cases

The API should use the same business logic and permission checks as the Budget application itself.

1. Normal transactions

A normal transaction should be editable and deletable through the API if the authenticated user has permission to modify it.

Changing fields such as:

• date
• amount
• description
• vendor
• category
• notes

should result in the same recalculations that would occur when making the corresponding change in the Budget web interface.

For example, changing:

Category: Groceries

to:

Category: Restaurants

must update the corresponding budget/category calculations.

Likewise, changing the amount should update account balances and all relevant calculations.

---

2. Split transactions

Split transactions need special consideration.

For example:

Total: €100.00

Groceries:    €60.00
Household:    €25.00
Other:        €15.00

The API should either:

1. allow the complete split structure to be replaced as part of the transaction update, or
2. continue using the existing split endpoint for modifying splits.

One possible approach would be:

PATCH /transactions/{id}

for the transaction itself, while:

POST /transactions/{id}/splits

continues to manage the split structure.

The important point is that an external client should be able to perform a complete edit of a split transaction without having to use private/internal endpoints.

---

3. Transfers

Transfers require additional care because one logical transfer can involve more than one transaction/account.

For example:

Checking Account
       ↓ €500
Savings Account

Deleting or modifying only one side of such a transfer could leave inconsistent data.

Therefore, the API should explicitly define what happens when the transaction belongs to a transfer.

Possible approaches include:

• editing/deleting the complete transfer atomically, or
• rejecting modification of transfer transactions through the normal transaction endpoint and providing dedicated transfer endpoints.

For example:

PATCH /transfers/{id}
DELETE /transfers/{id}

would be a possible future extension.

I would prefer consistency with the existing Budget data model rather than allowing an API client to accidentally modify only one side of a transfer.

---

4. Reconciled transactions

A transaction that has already been reconciled may need additional protection.

The API should define whether:

• reconciled transactions can be edited,
• reconciled transactions can be deleted,
• or the transaction must first be unreconciled.

If Budget already has a specific rule for this in the web interface, the API should follow the same rule.

For example, an API response could indicate:

409 Conflict

if the requested operation would violate the reconciliation state.

---

5. Permissions and shared accounts

The API must enforce the same ownership/sharing rules as the Budget application.

A user should not be able to modify or delete a transaction merely because they know its transaction ID.

The server should verify that the authenticated user has permission to modify the associated account/transaction.

---

6. Non-existent transactions

For an unknown transaction ID:

PATCH /transactions/999999

should return an appropriate:

404 Not Found

The same error conventions as the existing transaction API should be used.

---

7. Idempotency and mobile clients

The existing transaction creation API supports idempotency, which is particularly useful for mobile clients where network connections can fail after the server has already processed a request.

The same general consideration would be useful for update/delete operations.

For example, a mobile client might send an update and then lose the connection before receiving the response.

A retry must not accidentally produce an inconsistent state.

If idempotency keys are not appropriate for PATCH/DELETE, the API should at least document the expected retry semantics.

---

8. Atomicity

An update should either succeed completely or fail without leaving partially modified data.

This is particularly important for:

• amount changes
• account changes
• category changes
• split transactions
• transfers
• reconciliation-related data

For example, changing a transaction from €50 to €75 must not update the transaction while leaving the account balance calculated as if the transaction were still €50.

Example: mobile client workflow

A mobile client could then implement the complete transaction workflow.

Read

GET /transactions/123

Edit

PATCH /transactions/123

{
  "category_id": 15
}

Delete

DELETE /transactions/123

This would allow a native mobile application to provide the same basic transaction lifecycle as the Budget web application without relying on undocumented internal endpoints.

API design considerations

I would recommend that the implementation:

• reuse the existing transaction domain/service logic where possible
• reuse existing authorization and ownership checks
• reuse existing validation rules
• reuse existing balance/budget recalculation mechanisms
• follow the existing OCS API response/error conventions
• document the new endpoints in the OpenAPI specification
• add automated API tests
• document the behavior for transfers, splits and reconciled transactions

Most importantly, the public API should remain the stable interface. External clients should not need to reverse-engineer or call internal frontend endpoints.

Possible future extension

Once transaction update/delete is available, the API could eventually be extended with dedicated operations for more complex transaction types.

For example:

PATCH /transfers/{id}
DELETE /transfers/{id}

However, I don't think transfer-specific endpoints are necessarily required for the initial implementation if normal transaction update/delete can safely handle the existing Budget data model.

Backwards compatibility

This should be a backwards-compatible addition to the existing API.

Existing endpoints:

GET /transactions
GET /transactions/{id}
POST /transactions

would remain unchanged.

The new functionality would add:

PATCH /transactions/{id}
DELETE /transactions/{id}

without changing the behavior of existing clients.

Motivation

A complete public transaction API is particularly useful for:

• native mobile applications
• alternative Budget clients
• automation scripts
• integrations
• accessibility-focused clients
• other future frontends

Budget already provides a public API for external clients, so adding transaction update and delete would make that API significantly more complete.

I would therefore like to propose this as an official extension of the public Budget API.

Thank you for considering it!
@otherworld-dev

[otherworld-dev]

I will add this. Now that there is a full app using the API, it makes sense for edit and delete to be there as well.

It will work the same way as the web UI, with a few extra checks, as an app doesn't see the warnings the web UI shows:

• Transfers: changing the amount, date or type of one side will be refused, otherwise the two sides stop matching. Category, notes and description can still be changed. Deleting one side leaves the other as a normal transaction, same as the web UI.
• Reconciled: a change that affects the balance will return a 409 unless the request confirms it.
• Splits: sending a category_id for a split transaction will return a 409, the categories are changed through /splits instead. I will also add DELETE /transactions/{id}/splits to remove a split.

Moving a transaction to another account and changing its status will be left out for the time being.

Balances are recalculated after every change, so an edit can't leave them wrong. For retries, PATCH just sets the values you send, so sending it again is safe, and a repeated DELETE returns 404, which you can treat as already deleted.

[otherworld-dev]

This is done and will be in the next release. It works the way I described above, the one addition is that deleting a reconciled transaction needs confirm_reconciled=true too. Each refusal comes back as a 409 with an error_code (transfer_leg, reconciled or split), and edit_available in /capabilities tells the app whether the server has these. Splitting a transaction in an account shared with you works over the API now as well, before it returned a 404.

The spec is in openapi.json on dev if you want to start on it before the release: https://github.com/otherworld-dev/Budget/blob/dev/budget/openapi.json, the docs page will go up with the release.