Transaction Categorization

Transaction Categorization

Transactions from Monobank and PrivatBank arrive with raw data — MCC codes, merchant names, amounts — but users think in categories: "How much did I spend on food?" This skill maps raw transaction data to human-meaningful spending categories.

Input/Output Example

Input: Transaction with description "Сільпо" and MCC 5411

Categorization process:

1. Check user overrides — no override for this merchant
2. Check MCC code 5411 (Grocery Stores) — maps to "Groceries"
3. Merchant pattern "сільпо" also matches "Groceries" — consistent, no conflict

Output: Category: Groceries, Subcategory: Supermarkets

Another example showing why priority order matters:

Input: Transaction with description "Bolt" and MCC 4121 (Taxicabs)

1. Check user overrides — none
2. Check MCC 4121 — maps to "Transportation"
3. Merchant pattern "bolt" — also matches "Transportation"

But what if "Bolt" had MCC 5812 (Restaurants)? That happens when Bolt Food processes a food delivery. The MCC says "Dining" but the merchant pattern for /bolt/ says "Transportation". This is why the priority chain exists — and why user overrides sit at the top.

Why This Priority Chain

The categorization priority is:

1. Transaction-specific override (txn_id) — the user explicitly corrected this one transaction
2. Merchant-specific override (merchant_name) — the user said "always categorize Amazon as Shopping"
3. MCC code mapping — the most reliable automated signal, assigned by the payment network based on the merchant's registered business type
4. Merchant name patterns — a fallback for when MCC is too generic or missing
5. Default: "Other" — uncategorizable transactions

MCC codes rank above merchant patterns because MCC is assigned by the payment network and reflects the actual business category, while merchant name matching is regex-based and can produce false positives (e.g., "Bolt" could be rides or food delivery). User overrides rank above everything because the user always knows best — if they categorize their gym membership as "Healthcare" instead of "Entertainment", that is their intent and should be respected.

Standard Category Mapping

Merchant Pattern Matching (Ukrainian Market)

MCC codes can be too generic — many small Ukrainian businesses register under broad codes. These patterns catch well-known Ukrainian merchants by name, improving accuracy for the local market.

const merchantPatterns = [
  { pattern: /сільпо|атб|metro|fozzy|novus|ашан/i, category: 'Groceries' },
  { pattern: /glovo|bolt\s*food|rocket/i, category: 'Dining' },
  { pattern: /uber|bolt|uklon/i, category: 'Transportation' },
  { pattern: /megogo|spotify|sweet\.tv|netflix/i, category: 'Subscriptions' },
  { pattern: /rozetka|prom\.ua|алло|comfy|ельдорадо/i, category: 'Shopping' },
  { pattern: /aroma\s*kava|lviv\s*croissants|пузата\s*хата/i, category: 'Dining' },
  { pattern: /окко|wog|upg|socar/i, category: 'Transportation' },
  { pattern: /аптека|подорожник|доброго\s*дня/i, category: 'Healthcare' },
  { pattern: /sport\s*life|gym/i, category: 'Healthcare' },
  { pattern: /київстар|vodafone|lifecell|укртелеком/i, category: 'Utilities' },
];

Categorization Function

function categorize(transaction, overrides) {
  // 1. Transaction-specific override — user explicitly corrected this transaction
  if (overrides[`txn:${transaction.id}`]) {
    return overrides[`txn:${transaction.id}`];
  }

  // 2. Merchant-specific override — user said "always categorize X as Y"
  const merchantKey = `merchant:${transaction.merchantName}`;
  if (overrides[merchantKey]) {
    return overrides[merchantKey];
  }

  // 3. MCC code — most reliable automated signal
  const mccCategory = mapMCC(transaction.mcc);
  if (mccCategory && mccCategory !== 'Other') {
    return mccCategory;
  }

  // 4. Merchant name patterns — fallback for generic/missing MCC
  for (const { pattern, category } of merchantPatterns) {
    if (pattern.test(transaction.description || transaction.merchantName)) {
      return category;
    }
  }

  // 5. Default
  return 'Other';
}

Auto-Tagging Rules

Tags add metadata beyond the single category. They help with queries like "show me recurring expenses" or "flag large purchases."

function autoTag(transaction, history) {
  const tags = [];
  if (transaction.pending) tags.push('pending');
  if (Math.abs(transaction.amount) > 5000) tags.push('large-expense');
  if (transaction.amount < 0 && hasRecentCharge(transaction, history)) tags.push('refund');
  if (isRecurring(transaction, history)) tags.push('recurring');
  if (transaction.iso_currency_code !== transaction.account_currency) tags.push('international');
  return tags;
}

Manual Override

Users can correct categorization at two levels:

{
  "overrides": {
    "merchant:Costco": "Groceries",
    "merchant:Amazon": "Shopping",
    "txn:txn_abc123": "Business Expense"
  }
}

When a user says "це бізнес-витрата" about a specific transaction, save a txn: override. When they say "Amazon — це завжди шопінг", save a merchant: override. Merchant overrides apply to all future transactions from that merchant.

Spending Analysis Queries

Adapt the response to what the user is actually asking: