---
updatedAt: 2026-07-22T00:10:49.000Z
agentTools:
  projectIndex: https://docs.cardda.com/llms.txt
---

# List transaction rules

Returns a paginated list of the company's transaction rules (automations that match
transactions and apply custom-column change effects). Each rule includes its
`custom_column_change_effects` and `related_merchants`. Optionally filter by `merchant_id`.
Requires the `transactions_rules_view` or `transactions_rules_manage` permission; hidden
rules are excluded for non-admins.


# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "version": "1.0.0",
    "title": "accounting API"
  },
  "servers": [
    {
      "url": "https://api.cardda.com"
    }
  ],
  "paths": {
    "/v1/transaction/rules": {
      "get": {
        "summary": "List transaction rules",
        "description": "Returns a paginated list of the company's transaction rules (automations that match\ntransactions and apply custom-column change effects). Each rule includes its\n`custom_column_change_effects` and `related_merchants`. Optionally filter by `merchant_id`.\nRequires the `transactions_rules_view` or `transactions_rules_manage` permission; hidden\nrules are excluded for non-admins.\n",
        "operationId": "listTransactionRules",
        "tags": [
          "Transaction rule"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/company_id"
          },
          {
            "$ref": "#/components/parameters/_start"
          },
          {
            "$ref": "#/components/parameters/_end"
          },
          {
            "$ref": "#/components/parameters/_order"
          },
          {
            "$ref": "#/components/parameters/_field"
          },
          {
            "name": "merchant_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Filter rules that reference the given merchant in their constraints."
          },
          {
            "name": "name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Filter by name."
          },
          {
            "name": "enabled",
            "in": "query",
            "required": false,
            "schema": {
              "type": "boolean"
            },
            "description": "Filter by enabled state."
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of transaction rules",
            "headers": {
              "Content-Range": {
                "description": "Range of items returned (end exclusive).",
                "schema": {
                  "type": "string",
                  "example": "0-25/14"
                }
              },
              "X-Total-Count": {
                "description": "Total number of rules.",
                "schema": {
                  "type": "integer",
                  "example": 14
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Transaction_rule"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "404": {
            "description": "The `company-id` header is missing or the caller is not a member of the company"
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Transaction rule"
    }
  ],
  "components": {
    "parameters": {
      "company_id": {
        "name": "company-id",
        "in": "header",
        "required": true,
        "description": "UUID of the company on whose behalf the request is made. Required for every Accounting endpoint.\nSee [The company-id header](https://docs.cardda.com/docs/company-id) for details on how to obtain\na value for this header and the error responses to expect when it is missing or invalid.\n",
        "schema": {
          "type": "string",
          "format": "uuid"
        },
        "example": "550e8400-e29b-41d4-a716-446655440000"
      },
      "_start": {
        "name": "_start",
        "in": "query",
        "required": false,
        "schema": {
          "type": "integer",
          "minimum": 0
        },
        "description": "If all the transactions where in an array, this would represent the index of the first item returned in the response"
      },
      "_end": {
        "name": "_end",
        "in": "query",
        "required": false,
        "schema": {
          "type": "integer",
          "minimum": 0
        },
        "description": "If all the transactions where in an array, this would represent the index of the last item returned in the response"
      },
      "_order": {
        "name": "_order",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string",
          "enum": [
            "asc",
            "desc"
          ]
        },
        "description": "The order method, which can be ascending or descending"
      },
      "_field": {
        "name": "_field",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string",
          "example": "created_at"
        },
        "description": "The field used to sort, the example illustrates a response that would be sorted by the creation date"
      }
    },
    "schemas": {
      "Transaction_rule": {
        "type": "object",
        "description": "A transaction rule — an automation that matches transactions against `constraints` and applies\ncustom-column change effects (categorization). Rules are company-scoped and gated by the\n`transactions_rules_view` / `transactions_rules_manage` permissions.\n",
        "required": [
          "id",
          "company_id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "example": "a1b2c3d4-e5f6-4a5b-8c9d-0e1f2a3b4c5d"
          },
          "company_id": {
            "type": "string",
            "format": "uuid",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "user_id": {
            "type": "string",
            "description": "The user who created the rule."
          },
          "name": {
            "type": "string",
            "example": "Categorizar AWS como Infraestructura"
          },
          "constraints": {
            "type": "object",
            "description": "Match expression evaluated against transactions (MongoDB-style operators, e.g. `$or` with\nper-merchant clauses).\n",
            "additionalProperties": true,
            "example": {
              "$or": [
                {
                  "merchant_id": "8e668a4e-8485-4248-86cc-a7a2201cf8c3"
                }
              ]
            }
          },
          "enabled": {
            "type": "boolean",
            "example": true
          },
          "hidden": {
            "type": "boolean",
            "example": false
          },
          "related_merchants": {
            "type": "array",
            "description": "Merchants referenced by the rule's constraints.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "name": {
                  "type": "string"
                },
                "image_url": {
                  "type": "string",
                  "nullable": true
                }
              }
            }
          },
          "custom_column_change_effects": {
            "type": "array",
            "description": "The custom-column changes applied when the rule matches.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "rule_id": {
                  "type": "string",
                  "format": "uuid"
                },
                "type": {
                  "type": "string",
                  "example": "Transaction::CustomColumnChangeEffect"
                },
                "custom_column_id": {
                  "type": "string",
                  "format": "uuid",
                  "nullable": true
                },
                "target_attribute": {
                  "type": "string",
                  "nullable": true
                },
                "target_value": {
                  "type": "string",
                  "nullable": true
                },
                "created_at": {
                  "type": "string",
                  "format": "date-time"
                },
                "updated_at": {
                  "type": "string",
                  "format": "date-time"
                }
              }
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ]
}
```