What are transaction rules?

Transaction rules are a tool within the MX Platform API that enable end users to quickly assign matching transactions to a specific category, even if that category differs from the one assigned by MX’s data enhancement. End users can define their own category and description for transactions that match a certain pattern; every past and future transaction which matches the pattern will automatically be assigned to that category.

Rules have a string used to find matching transactions (match_description), a category that the transaction will be put in (category_guid), and an optional description that overrides the transaction’s original description.

This guide will take you through the process of creating, updating, and deleting a transaction rule so you can get a feel for all the ins and outs involved in using this powerful feature.


1. Create a rule

First, we’ll need to create a new transaction rule. But you’ll need to keep a few things in mind when doing so.

When a rule is created by the end user, the MX Platform will find all transactions that match the match_description you provide. The category and description of any matching transactions will then be changed to those provided by the end user.

The end user should decide which category to use and what the optional description should be. The category can be either a default MX category (accessible through the list default categories endpoint) or a custom category previously created by the end user (accessible through the list all categories endpoint). You, the partner, should determine the best match_description.

Matching is always performed between the match_description and the current transaction description. If a transaction’s description has been changed by any process or person, it’s the current transaction description that will be compared, not any previous or original description. With this in mind, note that if a rule updates the description of a transaction, and then you create another rule that matches the updated transaction description, that transaction will be associated with the newer rule — including updating to whatever the new rule’s description specifies.

Also, if you try to create a rule that has the same match_description as an existing rule on the same user object, a 409 Conflict error will be returned.

Endpoint:

POST /users/{user_guid}/transaction_rules

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/transaction_rules' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-u 'client_id:api_key' \
-H 'Content-Type: application/json' \
-d '{
      "transaction_rule": {
        "category_guid": "CAT-b1de2a04-db08-b6ed-f6fe-ca2f5b11c2d0",
        "description": "Wal-mart food storage",
        "match_description": "Wal-mart"
      }
    }'

Example response

1
2
3
4
5
6
7
8
9
10
11
{
  "transaction_rule": {
    "category_guid": "CAT-b1de2a04-db08-b6ed-f6fe-ca2f5b11c2d0",
    "created_at": "2018-10-02T22:00:50Z",
    "description": "Wal-mart food storage",
    "guid": "TXR-a080e0f9-a2d4-4d6f-9e03-672cc357a4d3",
    "match_description": "Wal-mart",
    "updated_at": "2018-10-02T23:54:40Z",
    "user_guid": "USR-22fc3203-b3e6-8340-43db-8e50b2f56995"
  }
}

1.1 Automatic creation

The MX system will automatically create rules under certain conditions. If the end user changes either the category or description of similar transactions three times, a rule will be created with the following attributes: match_description will be set to the original transaction description, category_guid will be the category set by the end user, and description will be the one set by the end user, if applicable.

A new rule will not be created if the transaction is already associated with an existing rule.


2. Update a rule

End users may want to change something about their rule, for instance changing the category or changing the description to something else. This is easily accomplished with the update transaction rule endpoint. There are a few things to keep in mind when updating a rule.

When the category_guid or description is updated, all transactions associated with the rule (past and future) will have the change applied. However, updating the match_description has no effect on existing associated transactions; instead, the rule will be applied to future transactions according to the new match_description.

Parameters

Parameter
category_guid
description
match_description

Endpoint:

PUT /users/{user_guid}/transaction_rules/{transaction_rule_guid}

Example request

1
2
3
4
5
6
7
8
9
10
11
curl -i -X PUT 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/transaction_rules/TXR-a080e0f9-a2d4-4d6f-9e03-672cc357a4d3' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-u 'client_id:api_key' \
-H 'Content-Type: application/json' \
-d '{
      "transaction_rule": {
        "category_guid": "CAT-b1de2a04-db08-b6ed-f6fe-ca2f5b11c2d0",
        "description": "Wal-mart food storage",
        "match_description": "Wal-mart"
      }
    }'

Example response

1
2
3
4
5
6
7
8
9
10
11
{
  "transaction_rule": {
    "category_guid": "CAT-b1de2a04-db08-b6ed-f6fe-ca2f5b11c2d0",
    "created_at": "2018-10-02T22:00:50Z",
    "description": "Walmart",
    "guid": "TXR-a080e0f9-a2d4-4d6f-9e03-672cc357a4d3",
    "match_description": "Wal-mart",
    "updated_at": "2018-10-02T23:54:40Z",
    "user_guid": "USR-22fc3203-b3e6-8340-43db-8e50b2f56995"
  }
}

3. Delete a rule

Rules can also be deleted. However, when a rule is deleted, the transactions associated with the rule will be unchanged except for the association being removed. In other words, the category and description applied by the rule will remain rather than being returned to their original state.

Endpoint:

DELETE /users/{user_guid}/transaction_rules/{transaction_rule_guid}

Example request

1
2
3
curl -i -X DELETE 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/transaction_rules/TXR-a080e0f9-a2d4-4d6f-9e03-672cc357a4d3' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-u 'client_id:api_key'