Plaid Category Mapping

Primary categories. The top-level groupings:

Access categories on transactions. The personal_finance_category field is available on every transaction from /transactions/sync:

const { added } = await syncTransactions(client, accessToken, cursor);

for (const txn of added) {
  const primary = txn.personal_finance_category?.primary;
  const detailed = txn.personal_finance_category?.detailed;
  const confidence = txn.personal_finance_category?.confidence_level;

  console.log(`${txn.name}: ${primary} / ${detailed} (${confidence})`);
  // "Starbucks: FOOD_AND_DRINK / FOOD_AND_DRINK_COFFEE (VERY_HIGH)"
}

Build a custom mapping layer. Map Plaid categories to your app's categories:

const CATEGORY_MAP: Record<string, string> = {
  FOOD_AND_DRINK: "Food",
  FOOD_AND_DRINK_RESTAURANTS: "Dining Out",
  FOOD_AND_DRINK_GROCERIES: "Groceries",
  FOOD_AND_DRINK_COFFEE: "Coffee",
  TRANSPORTATION: "Transport",
  TRANSPORTATION_GAS: "Gas",
  TRANSPORTATION_PARKING: "Parking",
  RENT_AND_UTILITIES: "Bills",
  ENTERTAINMENT: "Fun",
  GENERAL_MERCHANDISE: "Shopping",
  INCOME: "Income",
  TRANSFER_IN: "Transfer",
  TRANSFER_OUT: "Transfer",
};

function mapCategory(txn: Transaction): string {
  const detailed = txn.personal_finance_category?.detailed;
  const primary = txn.personal_finance_category?.primary;

  // Try detailed first, fall back to primary
  return CATEGORY_MAP[detailed ?? ""] ??
         CATEGORY_MAP[primary ?? ""] ??
         "Other";
}

Aggregate spending by category:

function summarizeByCategory(transactions: Transaction[]) {
  const totals: Record<string, number> = {};

  for (const txn of transactions) {
    if (txn.amount > 0) { // Plaid: positive = money out
      const category = mapCategory(txn);
      totals[category] = (totals[category] ?? 0) + txn.amount;
    }
  }

  return Object.entries(totals)
    .sort(([, a], [, b]) => b - a)
    .map(([category, total]) => ({ category, total: total.toFixed(2) }));
}

Handle confidence levels. Plaid provides a confidence score for each category:

For low-confidence categories, consider letting users manually recategorize.