What are Transaction Rules?

Transaction rules empower end users to automatically assign a chosen category to all transactions that match a specific description — even if that category differs from the one assigned by MX’s data enhancement. 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 transactions will be put into (category_guid), and an optional description that overwrites the transaction’s original description.

This guide will take you through the process of creating, updating, and deleting a transaction rule.

1. Create a Rule

First, you’ll need to create a new transaction rule — but keep a few things in mind:

• When an end user creates a rule, the MX Platform will find all past and future transactions that match the match_description you provide. The category and description of all matching transactions will then change 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, it’s the current transaction description that will be compared, not any previous or original description. 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

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

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. An automatic rule will not be created if the transaction is already associated with an existing rule.

• 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.
  • description will be the one set by the end user, if applicable.

2. Update a Rule

End users may want to change something about their rule. For instance, they may want to change the category or description. The update transaction rule endpoint accomplishes this.

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

Endpoint:

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

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

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. When a rule is deleted, the transactions associated with the rule will be unchanged. However, the association will be removed. In other words, the new category and description applied by the rule will remain rather than being returned to their original state. The deleted rule will not be applied to any future transactions.

Endpoint:

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

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'