What are Custom Categories?

While MX provides more than 100 default categories and subcategories, custom categories allow partners and end users to create a new category in addition to those defaults. For instance, an end user with multiple pets could create a category for Rover, Spot, and Scooby. Or an end user could break their 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_default field is true.
• Furthermore, you can’t create subcategories of subcategories; the parent of a custom category must be at the top level. In other words, its parent_guid field is null.
• 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_default field will be false.

1. 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. Currently, the MX Platform API doesn’t offer webhooks related to custom categories.

In the example below, 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

1
2
3
4
5
6
7
8
9
10
11
curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/categories' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
      "category": {
        "metadata": "Super cool extra info.",
        "name": "Online Shopping",
        "parent_guid": "CAT-aad51b46-d6f7-3da5-fd6e-492328b3023f"
      }
    }'

1
2
3
4
5
6
7
8
9
10
11
12
{
  "category": {
    "created_at": "2020-08-26T20:31:41Z",
    "guid": "CAT-3684d909-4b77-481c-99bf-8d87c6aa2c62",
    "is_default": false,
    "is_income": null,
    "metadata": "Super cool extra info.",
    "name": "Online Shopping",
    "parent_guid": "CAT-aad51b46-d6f7-3da5-fd6e-492328b3023f",
    "updated_at": "2020-08-26T20:31:41Z"
  }
}

2. Assign a Custom Category

Now that you’ve got a new custom category, it’s likely that the end user will want to actually use it. That may include recategorizing a single transaction or creating a transaction rule. We’ve actually got a separate guide that explains transaction rules in detail, so we won’t go over them much here except for a few key features.

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. So, 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.

3. 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 below. The one thing you can’t change is the parent_guid.

Endpoint:

PUT /user/{user_guid}/categories

1
2
3
4
5
6
7
8
9
curl -i -X PUT 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/categories/CAT-3684d909-4b77-481c-99bf-8d87c6aa2c62' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
      "category": {
        "name": "Web shopping"
      }
    }'

1
2
3
4
5
6
7
8
9
10
11
12
{
  "category": {
    "created_at": "2020-08-26T20:31:41Z",
    "guid": "CAT-3684d909-4b77-481c-99bf-8d87c6aa2c62",
    "is_default": false,
    "is_income": null,
    "metadata": null,
    "name": "Web shopping",
    "parent_guid": "CAT-aad51b46-d6f7-3da5-fd6e-492328b3023f",
    "updated_at": "2020-08-26T22:29:03Z"
  }
}

4. Delete a Custom Category

You can delete custom categories, but if you do, you should keep in mind 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 you used above, Shopping.

Endpoint:

DELETE /users/{user_guid}/categories/{category_guid}

1
2
3
curl -i -X DELETE 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/categories/CAT-3684d909-4b77-481c-99bf-8d87c6aa2c62' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json'