Terminal
Terminal/Skill
Suggests expense categories for uncategorized Mercury transactions, then writes the ones you approve back to Mercury through the mercury command line tool.
By Mercury
Works with
npx skills add mercurytechnologies/mercury-skills --skill mercury-autocategorize-transactionsSuggest expense categories for uncategorized Mercury transactions based on each transaction's counterparty, description, and Mercury-assigned merchant type. The skill batches the suggestions into a single review table, lets the user approve or edit, then applies the chosen categories with mercury transactions update.
Updates are written one transaction at a time and always require user confirmation before any write.
| Parameter | Default | Description |
|---|---|---|
dateRange | Last 30 days | Window of transactions to evaluate. |
accountFilter | All accounts | List of specific account IDs to include. |
onlyUncategorized | true | If true, skip transactions that already have a category. Set false to suggest re-categorization. |
confidenceThreshold | 0.6 | Suggestions below this confidence are flagged "Needs review" rather than auto-applied. |
1. Run `date +%Y-%m-%d` to get today's date.
2. Run `mercury categories list --max-items -1 --format jsonl`
to get the organization's full list of expense categories.
Each category has: id, name, optional description.
3. (Optional but recommended) Pull a 90-day window of already-categorized
transactions to learn which counterparty -> category mappings the
organization uses today:
mercury transactions list \
--start <today - 90 days> --end <today> \
--status sent \
--max-items -1 --format jsonl
Build counterpartyHistory[counterpartyName] = mode(category)
so suggestions follow the org's actual conventions instead of
guessing from the category name alone.
mercury transactions list \
[--account-id <id> ...] \
--start <dateRange.start> --end <dateRange.end> \
--status sent \
--max-items -1 --format jsonl
IF onlyUncategorized:
target = transactions where category is null/empty
ELSE:
target = all transactions in the window
Use --status sent so we don't categorize a pending transaction that may later post with different details.
For each target transaction, compute a suggested categoryId and a confidence score in [0, 1] from the strongest signal available, in this priority order:
1. counterpartyHistory match (confidence: 0.9)
IF txn.counterpartyName IN counterpartyHistory:
suggestion = counterpartyHistory[txn.counterpartyName]
reason = "Org has previously categorized {N} transactions
from '{counterpartyName}' as '{category}'"
2. mercuryCategory mapping (confidence: 0.75)
Mercury assigns a `mercuryCategory` (merchant type) to most card
transactions. Map common values to the closest org category by name
match -- e.g. "Software" -> Software, "Restaurants" -> Meals,
"RideShare" -> Travel. If the mapping is exact, use it.
3. Counterparty name keyword match (confidence: 0.6)
Match the lowercased counterpartyName / description against category
names and known keywords:
"aws", "gcp", "azure" -> Cloud Services
"github", "linear", "figma" -> Software
"uber", "lyft", "delta" -> Travel
"doordash", "blue bottle" -> Meals
"stripe payout" -> Revenue (income)
"gusto", "rippling" -> Payroll
Build this list from the actual category list returned in Step 1 --
never invent a category name that isn't in the org's list.
4. No confident signal (confidence: < 0.6)
suggestion = null
reason = "No confident match -- needs manual review"
Important: every suggestion.categoryId must come from the categories list returned in Step 1. Never invent a category.
| # | Date | Counterparty | Amount | Mercury Type | Suggested Category | Confidence | Reason |
Sort by confidence descending, with "Needs review" rows last.
Summary line:
"{N} transactions to categorize. {auto} ready to apply ({threshold}+ confidence),
{review} need review."
Writes happen one row at a time and only after the user explicitly approves the batch (or hand-edits rows). Never auto-apply without confirmation.
Prompt the user with three options:
1. Apply all "ready" rows as suggested
2. Apply a subset (user picks row numbers)
3. Edit one row -- user supplies a different categoryId or
types a category name; resolve it against the Step 1 list.
IF user does not explicitly approve:
STOP. Do not write.
FOR EACH approved row:
mercury transactions update \
--transaction-id <txn.id> \
--category-id <suggestion.categoryId>
Capture exit status. On error, follow mercury-shared error handling
(retry transients up to 2x, surface 400s verbatim, stop on 401/403).
After the loop, print a summary:
Updated {applied} transactions. {failed} failed -- see errors above.
Categorizing transactions Mar 30 - Apr 29, 2026 (1 account, status=sent)
Loaded 18 categories. Built history from 612 already-categorized transactions.
Found 14 uncategorized transactions:
| # | Date | Counterparty | Amount | Mercury Type | Suggested | Conf | Reason |
|---|------------|------------------------|-----------|--------------|----------------|-------|------------------------------------------------|
| 1 | 2026-04-02 | AWS | -$8,432.00| CloudServices| Cloud Services | 0.92 | Org has 23 prior 'AWS' txns as Cloud Services |
| 2 | 2026-04-04 | GitHub | -$84.00 | Software | Software | 0.91 | Org has 11 prior 'GitHub' txns as Software |
| 3 | 2026-04-09 | Uber | -$28.40 | RideShare | Travel | 0.75 | Mercury merchant type maps to Travel |
| 4 | 2026-04-12 | Blue Bottle Coffee | -$12.45 | Restaurants | Meals | 0.75 | Mercury merchant type maps to Meals |
| 5 | 2026-04-18 | NewTech Solutions |-$18,500.00| (none) | -- | <0.6 | No confident match -- needs manual review |
...
12 ready to apply (>=0.6 confidence), 2 need review.
Apply all ready rows? (a)pply / (s)ubset / (e)dit / (c)ancel: a
Updating...
#1 AWS -> Cloud Services OK
#2 GitHub -> Software OK
...
Updated 12 transactions. 0 failed.
2 still need review (#5, #11) -- ask the user how to categorize them.
mercury categories list output. Fabricating a category name will fail with a 400.--transform 'transactions.#.{id,amount,counterpartyName,category,categoryId,mercuryCategory,description,postedAt}' on the history pull to keep the 90-day window small in context.mercury transactions update accepts only --category-id and --note. To clear a category later, send null per the CLI's --help.mercury-receipt-upload.