FreshBooks Expense Category Badge

WHAT IT DOES

This userscript transforms your FreshBooks expense list into a categorized visual dashboard. It reads the category from each expense entry and displays a compact, color-coded badge directly on each expense row. Each category (Office Supplies, Travel, Meals, Software, Utilities, Marketing, Professional Services, and any custom categories you define) is assigned a distinct color that makes expense distribution instantly visible. Beyond individual badges, the script provides a summary panel showing total spending by category with percentage breakdowns, giving you a quick snapshot of where your money is going. A category filter bar lets you click any category to show only expenses in that category, turning your expense list into an interactive filtering tool. This helps business owners, accountants, and finance teams quickly analyze spending patterns, identify cost centers, and prepare for tax reporting without exporting data to spreadsheets.

WHERE IT RUNS

The script runs on all FreshBooks web application pages at *.freshbooks.com/*, with automatic detection of expense list views including the main expenses screen, project-specific expenses, and any page displaying expense tables. It works across all FreshBooks interfaces by using multiple selector strategies to find expense rows, categories, and amounts. The script detects dynamic content loading and re-applies badges whenever the expense list changes, including after filtering, sorting, or pagination. It runs across the entire FreshBooks domain, ensuring coverage whether you're reviewing all expenses, filtering by client, or viewing expense reports.

HOW TO USE

Install the script via the BotGentz extension and navigate to any expense list in FreshBooks. Category badges will appear automatically on every expense row. Each badge shows the category name with a color that you can customize. Use the panel controls to toggle badges on or off, show or hide the spending summary, or enable the category filter bar. The summary panel appears above your expense list showing total spending and a breakdown by category with dollar amounts and percentages. The filter bar appears as a sticky row with buttons for each category - click any button to show only expenses in that category, or click "All" to reset the view. You can customize the color for any category using the color picker in the panel, or add new categories with custom colors to match your chart of accounts. The "Refresh badges" button manually reapplies all badges if the page updates.

THE MECHANISM - CATEGORY DETECTION, AGGREGATION, AND VISUAL FILTERING

This script identifies expense categories by scanning each expense row using a cascading selector strategy. It first looks for FreshBooks' specific category elements including .category, .expense-category, [data-test="category"], and .category-name. When those fail, the script scans for tags, badges, or labels that might contain category information, and finally analyzes cell text for common category keywords. Once a category is detected, the script maps it to a color using either the user's custom color mappings or the default scheme. The badge is created as a DOM element with inline styles and inserted into the expense row's description cell. For the summary, the script aggregates total spending by category by parsing amounts from each row, calculating both total dollars and percentage of overall spending. The filter bar works by toggling the display property of expense rows based on whether their category matches the selected filter, providing instant visual filtering without page reloads. All amounts are parsed by stripping currency symbols and non-numeric characters, ensuring accurate financial calculations.

THE PANEL

The control panel appears as a floating, draggable element that you can position anywhere on the FreshBooks page. Drag by the header to reposition it, and the position is saved per site using GM_setValue so it stays where you left it across sessions. Release the panel near any edge and it snaps into place, keeping your workspace organized. Click the panel header to collapse it into a small bubble showing only the label emoji (🏷️), minimizing distraction while keeping controls accessible. Drag from the bubble to restore the full panel. The panel automatically resizes to fit its content and includes all setting toggles, color management controls, and action buttons. Press the Escape key to quickly collapse the panel to its minimized state. The panel remains visible across page navigation within FreshBooks, with badges updating automatically as you move between views.

PLEASE NOTE

This script requires the free BotGentz extension to function. It is designed for FreshBooks users who need visual categorization and spending analysis without leaving the application. The script reads only visible expense data from the DOM - it does not access FreshBooks' API, your account credentials, or any sensitive information. All settings (category colors, toggle states, and panel position) are stored locally using GM_setValue and never leave your browser. The script does not modify your FreshBooks data - it only enhances the visual presentation of the expense list and provides local summary calculations. If FreshBooks updates its website structure, the script may need to be updated to match new selectors; check for updates if the badges stop appearing. The script works with both standard FreshBooks categories and any custom categories you've created, with the ability to add color mappings for new categories through the panel.