What are custom categories?

While MX provides more than 100 default categories and subcategories ranging from auto loans to pet care, 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 someone could break their hobbies into individual categories like music, woodworking, and disc golf.

There are a couple 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 parent_guid field is null.
  • Furthermore, you can’t create subcategories of subcategories; the parent of a custom category must be at the top level.

Categories are closely related to both transactions and transaction rules, so we’ll also be talking about those resources a lot. After all, the whole point of a category is to apply it to particular transactions so they can be grouped, tracked, and easily understood.

You can get a list of all default categories using the list default categories endpoint. This list doesn’t change, so you can feel free to cache it on your end if that works better for your product. If you want to see the custom categories we’ll be creating here, however, you’ll need to use the list all categories endpoint, which includes both default categories and custom categories. You can tell the difference by looking at the is_default field: if it’s false, then you’ve got yourself a custom category.

Just to make your life a little easier, here’s a list of default category names showing both parents and subcategories; these are the strings you’ll find in the name field a category object, or in the category field of a transaction object.

  • Auto & Transport
    • Auto Insurance
    • Auto Payment
    • Gas
    • Parking
    • Public Transportation
    • Service & Parts
  • Bills & Utilities
    • Domain Names
    • Fraud Protection
    • Home Phone
    • Hosting
    • Internet
    • Mobile Phone
    • Television
    • Utilities
  • Business Services
    • Advertising
    • Legal
    • Office Supplies
    • Printing
    • Shipping
  • Education
    • Books & Supplies
    • Student Loan
    • Tuition
  • Entertainment
    • Amusement
    • Arts
    • Movies & DVDs
    • Music
    • Newspapers & Magazines
  • Fees & Charges
    • ATM Fee
    • Banking Fee
    • Finance Charge
    • Late Fee
    • Service Fee
    • Trade Commissions
  • Financial
    • Financial Advisor
    • Life Insurance
  • Food & Dining
    • Alcohol & Bars
    • Coffee Shops
    • Fast Food
    • Groceries
    • Restaurants
  • Gifts & Donations
    • Charity
    • Gift
  • Health & Fitness
    • Dentist
    • Doctor
    • Eyecare
    • Gym
    • Health Insurance
    • Pharmacy
    • Sports
  • Home
    • Furnishings
    • Home Improvement
    • Home Insurance
    • Home Services
    • Home Supplies
    • Lawn & Garden
    • Mortgage & Rent
  • Income
    • Bonus
    • Interest Income
    • Paycheck
    • Reimbursement
    • Rental Income
  • Investments
    • Buy
    • Deposit
    • Dividend & Cap Gains
    • Sell
    • Withdrawal
  • Kids
    • Allowance
    • Baby Supplies
    • Babysitter & Daycare
    • Child Support
    • Kids Activities
    • Toys
  • Personal Care
    • Hair
    • Laundry
    • Spa & Massage
  • Pets
    • Pet Food & Supplies
    • Pet Grooming
    • Veterinary
  • Shopping
    • Books
    • Clothing
    • Hobbies
    • Sporting Goods
  • Taxes
    • Federal Tax
    • Local Tax
    • Property Tax
    • Sales Tax
    • State Tax
  • Transfer
    • Credit Card Payment
    • Transfer for Cash Spending
    • Mortgage Payment
  • Travel
    • Air Travel
    • Hotel
    • Rental Car & Taxi
    • Vacation
  • Uncategorized
    • Cash
    • Check

1. Create a custom categegory

Before creating a custom category, the end user will need to figure out which parent category they want to use. You can do this with the list default categories endpoint or from a cached list, as discussed above.

Once you’ve got a parent category, you’ll need to include it’s GUID as the parent_guid in the create request, as well as a name for your 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, and 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, but this may change in the future.

In the example below, we’ve used Shopping (CAT-aad51b46-d6f7-3da5-fd6e-492328b3023f) as the parent for our new Online Shopping category.

Endpoint:

POST /user/{user_guid}/categories

Example request

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"
      }
    }'

Example response

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 to transactions

Now that we’ve got a new custom category, it’s likely that someone will want to actually use it. That means creating a new 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.

Rules allow 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 Online shopping. Rules override MX’s automatic categorization.

We may introduce new ways to use custom categories in the future, but for right now, transaction rules are the way to go.


3. Update a custom category

There will certainly be times where someone needs to change the name of a category, maybe due to a misspelling or some other reason. Or you may want to update the metadata associated with the custom category. In these cases, you’ll want to use the update custom category endpoint.

You can update the fields shown below. The one thing you can’t change is the parent_guid. Once you’ve given a custom category a parent guid, it’s got to stay there.

Parameter Required?
metadata No
name No

You should also know another thing: If your 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.

Endpoint:

PUT /user/{user_guid}/categories

Example request

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"
      }
    }'

Example response

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 also delete custom categories, but if you do, you should keep in mind 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 Web Shopping, but then deleted the Web Shopping category, all Amazon transactions would be set to the parent we used above, Shopping.

Endpoint:

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

Example request

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'