> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Using Transaction Rules for Automatic Categorization

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](/api-reference/platform-api/reference/categories) endpoint) or a custom category created by the end user (accessible through the [list all categories](/api-reference/platform-api/reference/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`

<CodeGroup>
  ```shell Request theme={null}
  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"
        }
      }'

  ```

  ```json Response theme={null}
  {
      "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"
      }
  }

  ```
</CodeGroup>

## 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](/api-reference/platform-api/reference/transaction-rules) 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}`

<CodeGroup>
  ```shell Request theme={null}
  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"
        }
      }'

  ```

  ```json Response theme={null}
  {
      "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"
      }
  }

  ```
</CodeGroup>

## 3. Delete a Rule

To delete a transaction rule, use the [delete transaction rule](/api-reference/platform-api/reference/transaction-rules) endpoint.

`Endpoint: DELETE /users/{user_guid}/transaction_rules/{transaction_rule_guid}`

<CodeGroup>
  ```shell Request theme={null}
  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'

  ```
</CodeGroup>