Skip to content

A local-first personal finance app

Updated API Documentation for Splitting Transactions (#7593)

rboaduf68e4fbb2a14
diff --git a/.github/actions/docs-spelling/expect.txt b/.github/actions/docs-spelling/expect.txt
index 24737f3705..f2bd8ba66f 100644
--- a/.github/actions/docs-spelling/expect.txt
+++ b/.github/actions/docs-spelling/expect.txt
@@ -61,6 +61,7 @@ Dockerfiles
Dominguez
DUSSDEDDXXX
DUSSELDORF
+ecf
EDATE
ENTERCARD
Entra
@@ -140,8 +141,6 @@ pluggyai
Poste
PPABPLPK
prefs
-Primoco
-Priotecs
proactively
Qatari
QNTOFRP
@@ -172,7 +171,6 @@ SWEDBANK
SWEDNOKK
Synology
systemctl
-tada
taskbar
templating
THB
diff --git a/packages/docs/docs/api/reference.md b/packages/docs/docs/api/reference.md
index 6c9cc17afb..37e4ac2ffb 100644
--- a/packages/docs/docs/api/reference.md
+++ b/packages/docs/docs/api/reference.md
@@ -164,11 +164,26 @@ These are types.
A split transaction has several sub-transactions that split the total
amount across them. You can create a split transaction by specifying
-an array of sub-transactions in the `subtransactions` field.
+an array of sub-transactions in the `subtransactions` field. This field is primarily used during creation and retrieval.
-Subtransactions can specify the following fields, and `amount` is the only required field:
+In practice, updating subtransactions individually may not work reliably. To modify split transactions, update the parent transaction and provide the full `subtransactions` array.
+
+Subtransactions are treated as full transaction records and are validated similarly to regular transactions.
+
+In practice, API creation commonly requires at least the fields below.
- `amount`
+- `account`
+- `date`
+- `parent_id`
+- `is_child: true`
+
+Additionally, child transactions should explicitly set:
+
+- `is_parent`: false
+
+Optional fields include:
+
- `category`
- `notes`
@@ -176,6 +191,47 @@ If the amounts of the sub-transactions do not equal the total amount
of the transaction, currently the API call will succeed but an error
will be displayed within the app.
+#### Parent Transaction Requirements
+
+A transaction must be marked with `is_parent: true` before subtransactions can be added.
+
+If `is_parent` is not set to `true` on the parent transaction, any provided `subtransactions` will be ignored and the transaction will be treated as a standard (non-split) transaction. No split will be created.
+
+Subtransactions are only processed when the parent transaction has `is_parent: true`.
+
+If subtransactions are provided but are invalid (e.g. missing required fields such as `account` or `date`), the API will return a validation error (HTTP 400) indicating that required transaction fields are missing.
+
+A working example of API fields:
+
+**Note:** When creating a new split transaction, you typically don't need to provide an `id` for the parent; the system will generate one. The parent transaction's `amount` should equal the sum of all subtransaction amounts.
+
+```js
+{
+ "id": "parent-id",
+ "is_parent": true,
+ "subtransactions": [
+ {
+ "amount": 142000,
+ "account": "9c1e5de4-ecf8-41c2-8a97-4a1e8bc385c9",
+ "date": "2024-08-12",
+ "parent_id": "parent-id",
+ "is_child": true,
+ "is_parent": false,
+ "category": "71376207-72f9-4b2b-ae24-0931a226f76a",
+ },
+ {
+ "amount": 150,
+ "account": "9c1e5de4-ecf8-41c2-8a97-4a1e8bc385c9",
+ "date": "2024-08-12",
+ "parent_id": "parent-id",
+ "is_child": true,
+ "is_parent": false,
+ "category": "315d3776-d2a8-4d82-8a69-648b0d80125a",
+ }
+ ]
+}
+```
+
#### Transfers
Existing transfers will have the `transfer_id` field which points to the transaction on the other side. **You should not change this** or you will cause unexpected behavior. (You are allowed to set this when importing, however.)