Category Taxonomy

We categorise transactions at up to 4 levels of increasing precision, with level 1 being the highest, most general level of our categorisation taxonomy. Levels 1 and 2 are produced by our categorisation engine, which leverages many fields from the transaction to determine an income or spending category. Levels 3 and 4 are from our counterparty detection engine, which detects the retailer in the transaction in the vast majority of cases from the transaction description alone. In the event a counterparty was not detected, these fields will be blank.

An example of the categorisation taxonomy for a "Tesco" transaction is as follows:

• Shopping (L1), Groceries (L2), Supermarket (L3)

The focus of the categorisation outputs at L1 and L2 is categorising the exact nature of the spend, whereas L3 and L4 provide the retailer and categorisation of the main type of product or service that the retailer provides. As an example, purchasing some confectionery at a petrol station would have the following categorisation taxonomy:

• Entertainment (L1), Eating out (L2), Petrol (L3)

While there is general consistency between the outputs from the categorisation and counterparty engines, the above highlights how they are independent engines, and the focus of the L3 categorisation is the core product the counterparty sells or the service provided, not necessarily what was purchased by the user.

Levels 1 and 2

Our machine learning based model produces level 1 and level 2 categorisation. Every transaction will be assigned level 1 and level 2 categories. If a transaction has no description, or the description states explicitly "No description", the categorisation model relies on other available features such as the merchant category code (MCC), amount, and account type. If no features produce a confident prediction, the transaction is categorised as uncategorized. This section helps understand how we generally allocate transactions to each L1 and L2 category.

Misconceptions and quotes from past exercises:

• "Coffee shops and (non-petrol) service station spends, e.g. Welcome Break, have been incorrectly allocated a l2_category_name of eating-out."

The l2_category_name of eating-out captures spending at restaurants, fast food, drinks at bars, coffee shop spending and snacks from stores such as service stations.

• "A large number of Amazon and eBay transactions were not categorised and allocated a l2_category_name of 'general'"

general is not a catch-all for transactions we cannot categorise. It stands for General merchandise, and it has the friendlyName as such, and thus is appropriate for Amazon and eBay purchases.

It is important to note that level 1 and 2 categorisation attempts to categorise the nature of the spend, not the categorisation of the counterparty purchased from. For instance, buying a chocolate bar from a petrol station will be categorised as eating-out but purchasing fuel from the same petrol station will be categorised as gasoline.

Overriding categories

The model-produced L1 and L2 values on a transaction (l1CategoryGroupName, l2CategoryName, and related fields) are set by the categorisation engine during enrichment.

You can assign a category override to an enriched transaction using Update an enriched transaction. Set userCategoryId in the request body to either:

• a custom category UUID returned from Create a custom category for a user, or
• a standard Moneyhub L2 category ID (for example "22"). See Retrieve all standard categories for the available values.

The override is stored in mhInsights.userCategoryId. The model-produced L1 and L2 fields remain on the transaction alongside the override.

The required recategorisationType query parameter controls how the override is applied:

• single: applies the category override to this transaction only.
• future: applies the override to this transaction and creates a matching rule for that user. Future transactions with the same description and amount will receive the same userCategoryId during enrichment.

Transactions with active splits cannot be recategorised. These transactions have userCategoryId set to the reserved mixed category. Clear the splits with Delete transaction splits before recategorising.

Levels 3 and 4

The level 3 categorisation taxonomy is the counterparty (industry) category: the core product the transaction counterparty sells or service provided. The L3 categorisations will only be present when we have detected a transaction counterparty. While the focus is on the core product or service provided by the counterparty, we report more fine-grained details if the transaction description and other attributes, such as amount, help us determine a more specialised version of that service/product. For example, LV life insurance has a level 3 category of "insurance-life" and LV travel insurance has a level 3 category of "insurance-travel".

In the majority of cases, when we identify a counterparty with the level 3 category "loans", we additionally state the predominant type of loan provided by that counterparty as the level 4 category.

Example transactions

Custom Categories

Custom categories are user-specific categories that you create and manage per user. They can be created, listed, and deleted via the API. The returned customCategoryId is used as the userCategoryId when recategorising a transaction.

When a custom category is deleted, the userCategoryId override is cleared on any transactions that were assigned that category. Deleting a user also deletes that user's custom categories and associated category rules.