# Category Rules

> Solarium docs. All requests are `POST https://api.trysolarium.com/graphql/` with `Authorization: Bearer <api key>` and a JSON body `{"query": ..., "variables": ...}`. Every query and mutation takes an `organizationId` (find it with `myOrganizations`). Index of all pages: https://trysolarium.com/llms.txt

Auto-categorization rules map vendor name patterns to accounts. When a transaction's merchant name matches a rule's pattern, Solarium automatically fills in the expense category during import and review. Rules are deterministic and auditable — they complement the AI agent's suggestions with a predictable, user-controlled layer.

## List Category Rules

List auto-categorization rules. Rules map vendor name patterns to accounts. When a transaction's merchant matches a pattern, Solarium auto-fills the category.

### Arguments

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `organizationId` | `UUID!` | Yes | Organization ID |
| `limit` | `Int` | No | Page size (default 25, max 200) |
| `offset` | `Int` | No | Number of records to skip |
| `search` | `String` | No | Filter by vendor pattern (case-insensitive) |
| `sortBy` | `String` | No | Field to sort by (e.g. vendorPattern, matchCount) |
| `sortDir` | `String` | No | asc or desc (default asc) |

### Request

```graphql
query {
  listCategoryRules(
    organizationId: "a1b2c3d4-..."
    limit: 10
    search: "tim"
  ) {
    items {
      id
      vendorPattern
      account { id name }
      matchCount
    }
    totalCount
    pageSize
    offset
  }
}
```

### Response

```json
{
  "data": {
    "listCategoryRules": {
      "items": [
        {
          "id": "r1a2b3c4-...",
          "vendorPattern": "%TIM HORTONS%",
          "account": {
            "id": "f7e6d5c4-...",
            "name": "Meals & Entertainment"
          },
          "matchCount": 34
        },
        {
          "id": "r5d6e7f8-...",
          "vendorPattern": "%TIMMIES%",
          "account": {
            "id": "f7e6d5c4-...",
            "name": "Meals & Entertainment"
          },
          "matchCount": 3
        }
      ],
      "totalCount": 2,
      "pageSize": 10,
      "offset": 0
    }
  }
}
```

## Create a Category Rule

Create an auto-categorization rule. The vendorPattern is matched case-insensitively against merchant names. Use SQL ILIKE patterns (% for wildcard).

### Arguments

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `organizationId` | `UUID!` | Yes | Organization ID |
| `vendorPattern` | `String!` | Yes | ILIKE pattern to match vendor names (e.g. "%SHOPIFY%", "%CANADA POST%") |
| `categoryId` | `UUID!` | Yes | Account ID to auto-assign when pattern matches |

### Request

```graphql
mutation {
  createCategoryRule(
    organizationId: "a1b2c3d4-..."
    vendorPattern: "%PETRO-CANADA%"
    categoryId: "vehicle-expense-uuid"
  ) {
    categoryRule {
      id
      vendorPattern
      account { id name }
    }
    success
    error
  }
}
```

### Response

```json
{
  "data": {
    "createCategoryRule": {
      "categoryRule": {
        "id": "r9a8b7c6-...",
        "vendorPattern": "%PETRO-CANADA%",
        "account": {
          "id": "vehicle-expense-uuid",
          "name": "Vehicle Expenses"
        }
      },
      "success": true,
      "error": null
    }
  }
}
```