Skip to main content
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 will decide on the category and optional description.. The category can be either a default MX category (accessible through the list default categories endpoint) or a custom category created by the end user (accessible through the list all categories endpoint). You must 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.
  • 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 
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"
      }
    }'


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

​
Automatic Creation

The MX system automatically creates rules under certain conditions. An automatic rule won’t 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, such as the category or description. The update transaction rule endpoint accomplishes this. 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.
Endpoint: PUT /users/{user_guid}/transaction_rules/{transaction_rule_guid} 
curl -i -X PUT 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/transaction_rules/UTR-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"
      }
    }'


{
    "transaction_rule": {
        "category_guid": "CAT-b1de2a04-db08-b6ed-f6fe-ca2f5b11c2d0",
        "created_at": "2018-10-02T22:00:50Z",
        "description": "Walmart",
        "guid": "UTR-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

To delete a transaction rule, use the delete transaction rule endpoint. Endpoint: DELETE /users/{user_guid}/transaction_rules/{transaction_rule_guid} 
curl -i -X DELETE 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/transaction_rules/UTR-a080e0f9-a2d4-4d6f-9e03-672cc357a4d3' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-u 'client_id:api_key'