Transaction Splits via API

You can now split a transaction using the API Gateway. These transactions split allow you to split a transaction's amount into different categories and/or projects, and include a description for each split.

Say for example you did a shop at a supermarket which incorporated groceries and gifts, you can split the transaction across the groceries and gifts categories.

Four new methods have been exposed to allow you to achieve this.

POST /transactions/{transactionId}/splits

This method will split a transaction up for you. This will set the main transaction's category to mixed and set the splits property on the transaction. To split the transaction, you need to send a body like the one below:

[
  {
    "categoryId": "std:5a7ff1f3-cd2c-4676-a368-caf09f2ca35a",
    "description": "Split 1",
    "amount": 200
  },
  {
    "categoryId": "std:eac238ec-3899-49ff-8cce-e3b9f4b1aede",
		"projectId": "c390a94f-2309-4cdf-8d02-b0c5304d9f66",
    "description": "Split 2",
    "amount": 400
  }
]

This is assuming that the transaction's amount sums to 600, otherwise a Bad Request error will be sent by the API.

Each split must have the following properties:

• categoryId
• description
• amount

The property projectId is optional.

GET /transactions/{transactionId}/splits

This will retrieve the transaction splits for a given transaction ID. This will return a response in the following format:

[
  {
		"id": "c390a94f-3824-4cdf-8d02-b0c5304d9f66",
    "categoryId": "std:5a7ff1f3-cd2c-4676-a368-caf09f2ca35a",
    "description": "Split 1",
    "amount": 200
  },
  {
		"id": "1d615ed3-1335-4269-b512-4a84acaf9d29",
    "categoryId": "std:eac238ec-3899-49ff-8cce-e3b9f4b1aede",
		"projectId": "c390a94f-2309-4cdf-8d02-b0c5304d9f66",
    "description": "Split 2",
    "amount": 400
  }
]

With this you can get a split's unique ID to perform a PATCH on the split to update the split's category ID, project ID and/or description.

PATCH /transactions/{transactionId}/splits/{splitId}

Use this method to update any of the following transaction split fields:

• categoryId
• projectId
• description

Note that you cannot update the split's amount, as this would lead to the splits not summing to the main transaction's amount.

If you wish to update the transaction split amounts, you will need to perform POST on the transaction again and overwrite the splits completely.

A simple patch to update the categoryId would look like this:

{
	"categoryId": "std:4b0255f0-0309-4509-9e05-4b4e386f9b0d"
}

The resultant response from the API would be the updated splits array after the PATCH has been applied - as if you had just made a call to GET /transactions/{transactionId}/splits straight after the call.

DELETE /transactions/{transactionId}/splits

To remove all the splits from a transaction and merge it back into one "split", use the DELETE method. This has a couple of implications:

• The splits array will be emptied and left at []
• The split with the largest monetary contribution (either positive or negative), will have that split's categoryId applied as the main transaction's categoryId, thus removing the mixed category.

You will be returned with an empty body on completion of the delete.