Custom Categories
While MX provides more than 100 default categories and subcategories, you can also create custom categories. For instance, someone with multiple pets could create a category for Rover, Spot, and Scooby. You can also break your hobbies into custom subcategories like music, woodworking, and disc golf.
There are several things to keep in mind, however:
- All custom categories must be subcategories of some existing parent category. You can't create new parent categories. In other words, custom categories must be nested under one of the default categories whose
is_defaultfield istrue. - You can't create subcategories of subcategories; the parent of a custom category must be at the top level. In other words, its
parent_guidfield isnull. - To list the custom categories for a user, you must use the list all categories endpoint, which includes both default categories and custom categories. For custom categories, the
is_defaultfield will befalse.
Create a Custom Category
Before creating a custom category, the end user will need to decide which parent category they want to use; the parent category must be both default (is_default: true) and top-level (parent_guid: null). They'll also need to provide a name for the custom category.
You can also include the optional metadata and skip_webhook parameters; metadata allows you to store any information you choose about the new category (MX recommends structured data like JSON). The skip_webhook parameter prevents MX from sending an associated webhook if it has been configured. The MX Platform API doesn't offer webhooks related to custom categories.
In the following example, you'll use Shopping (CAT-aad51b46-d6f7-3da5-fd6e-492328b3023f) as the parent for the new Online Shopping category.
Endpoint: POST /user/{user_guid}/categories
Assign a Custom Category
To use the new custom category, you can recategorize a single transaction or create a transaction rule.
Transaction rules empower end users to automatically assign similar transactions to a specific category — in this case, a custom category. Every past and future transaction that meets the criteria set out in the rule will be put in the category you specify. For instance, you could create a rule that assigns every transaction from Amazon to the custom Online shopping category. Rules override MX's data enhancement. See our separate guide that explains transaction rules in detail.
Update a Custom Category
There will certainly be times when either you or the end user need to change the name of a category. In these cases, you'll want to use the update custom category endpoint.
If the custom category is associated with a transaction rule and then you change the name, all the transactions associated with that rule will be updated with the new category name as well.
You can update the fields shown in the example. The one thing you can't change is the parent_guid.
Provide at least one of the following parameters. If no parameters are supplied, a 400 Bad Request error will be returned.
| Parameter | Required? |
|---|---|
metadata | No |
name | No |
Endpoint: PUT /user/{user_guid}/categories
Delete a Custom Category
You can delete custom categories, but if you do, note it will influence some related transaction rule behavior.
If the deleted category was associated with a rule, any transactions related to that rule will have their category field set to the parent of the deleted category. For example, if you had a rule that set all Amazon transactions to Online Shopping, but then deleted the Online Shopping category, all Amazon transactions would be set to the parent Shopping.
Endpoint: DELETE /users/{user_guid}/categories/{category_guid}