Skip to main content

​
Transaction Management

The transactions feature is the core of Budget Bee, allowing you to record, categorize, and analyze all your financial activities.

​
Overview

Transactions in Budget Bee can represent:
  • Income (positive amounts)
  • Expenses (negative amounts)
  • Transfers between accounts
  • Any other financial activity
Each transaction includes:
  • Amount and currency
  • Transaction date
  • Category
  • Status (paid, pending, etc.)
  • Optional description and reference number
  • Tags for additional organization

​
Creating Transactions

1

Open Transaction Dialog

Click the + button in the top right of the transactions page, or use keyboard shortcuts.
2

Fill in Details

Enter the transaction information:
​
name
string
required
A descriptive name for the transaction (e.g., “Monthly rent payment”)
​
amount
number
required
The transaction amount (use positive for income, negative for expenses)
​
currency
string
default:"USD"
Three-letter currency code (USD, EUR, GBP, etc.)
​
transaction_date
date
default:"Today"
When the transaction occurred
​
category_id
uuid
The category this transaction belongs to
​
status
string
default:"paid"
Transaction status: paid, pending, failed, or custom values
​
reference_no
string
Optional reference number (invoice number, check number, etc.)
​
description
string
Additional details about the transaction
3

Save Transaction

Click Save to create the transaction. It will appear immediately in your transactions list.

​
Viewing Transactions

The transactions page displays all your transactions in a powerful table interface: 
// Example from apps/web/app/(app)/transactions/page.tsx
export default function Page() {
  const isEditing = useEditorStore(s => s.is_editing);
  const transactionTableRef = React.useRef<HTMLFormElement>(null!);

  return (
    <div>
      <div className="flex items-start justify-between border-b p-2">
        <div className="flex flex-wrap gap-2">
          <FilterDialog />
          <FilterClear />
          <FilterPills />
        </div>

        <div className="flex gap-2">
          <DeleteButton />
          <EditButton />
          <DisplayDropdown />
        </div>
      </div>

      <div className="p-4 space-y-4">
        <TransactionsTable ref={transactionTableRef} />
      </div>
    </div>
  );
}

​
Table Features

Sortable Columns

Click any column header to sort by that field (amount, date, category, etc.)

Virtualized Scrolling

Handles thousands of transactions efficiently using TanStack Virtual

Inline Editing

Edit transactions directly in the table without opening dialogs

Bulk Selection

Select multiple transactions for bulk operations

​
Filtering Transactions

Budget Bee provides powerful filtering capabilities:

​
Available Filters

Filter transactions by date:
  • Last 7 days
  • Last 30 days
  • Last 90 days
  • Custom date range
  • Specific month or year
Filter by one or multiple categories. You can:
  • Select specific categories
  • Exclude categories
  • View uncategorized transactions
Filter by transaction amount:
  • Minimum amount
  • Maximum amount
  • Exact amount
  • Income only (positive amounts)
  • Expenses only (negative amounts)
Filter by transaction status:
  • Paid
  • Pending
  • Failed
  • Custom statuses
Filter transactions by currency code (USD, EUR, GBP, etc.)
Search transaction names and descriptions for specific keywords.

​
Using Filters

1

Open Filter Dialog

Click the Filter button in the toolbar above the transactions table.
2

Select Filter Criteria

Choose your filter options. You can combine multiple filters.
3

Apply Filters

Click Apply to filter the transaction list. Active filters appear as pills above the table.
4

Clear Filters

Click Clear All or remove individual filter pills to reset.
Filters are stored in your session, so they persist when you navigate away and return.

​
Bulk Editing

Edit multiple transactions at once:
1

Enable Edit Mode

Click the Edit button in the toolbar to enable bulk edit mode.
2

Select Transactions

Check the boxes next to transactions you want to edit, or click the header checkbox to select all visible transactions.
3

Modify Fields

Edit fields directly in the table. Changes are highlighted.Editable fields:
  • Amount
  • Currency
  • Category
  • Status
  • Transaction date
  • Name and description
4

Save Changes

Click Save to commit all changes, or Cancel to discard them.
Bulk edits cannot be undone. Make sure your changes are correct before saving.

​
Categories

Categories help organize your transactions:

​
Default Categories

Budget Bee automatically creates three categories for new users:
  • Food: Restaurant meals, groceries, snacks
  • Travel: Transportation, hotels, flights
  • Sales: Income from sales or services

​
Creating Custom Categories

See Categories for detailed information on creating and managing categories.

​
Import Transactions

Import transactions from external sources:
Import transactions from CSV files:
  1. Prepare a CSV file with headers: 
    date,name,amount,currency,category,status
2024-01-15,Coffee Shop,4.50,USD,Food,paid
2024-01-16,Gas Station,45.00,USD,Travel,paid
  2. Click Import and select your CSV file
  3. Map CSV columns to transaction fields
  4. Review and confirm the import

​
Export Transactions

Export your transaction data for backup or analysis: 
// Example from apps/web/components/settings/export-transactions.tsx
const handleExport = async () => {
  const db = await getDb();
  const res = await db
    .from("transactions")
    .select("*")
    .gte("transaction_date", startDateStr)
    .lt("transaction_date", endDateStr)
    .order("transaction_date", { ascending: false });

  const transactions = res.data;
  
  // Format and export based on selected format
  switch (exportFormat) {
    case "csv":
      downloadCSV(exportData, fileName);
      break;
    case "excel":
      downloadExcel(exportData, fileName);
      break;
    case "json":
      downloadJSON(exportData, fileName);
      break;
  }
};

​
Export Options

CSV

Comma-separated format compatible with Excel and other tools

Excel

Native Excel format (.xlsx) with proper formatting

JSON

Machine-readable format for programmatic processing

​
Customizing Exports

When exporting, you can:
  • Select specific date ranges
  • Choose which columns to include
  • Filter by category or status
  • Include or exclude transaction IDs

​
Transaction Status

Transactions can have different statuses:
  • Paid: Transaction completed successfully
  • Pending: Transaction awaiting completion
  • Failed: Transaction failed to process
  • Canceled: Transaction was canceled
  • Custom: Define your own status values
Status badges use color coding for quick visual identification.

​
Multi-Currency Support

Budget Bee supports transactions in multiple currencies: 
// Currency picker component
<CurrencyPicker
  value={currency}
  onValueChange={setCurrency}
/>
  • Choose from 150+ currencies
  • Each transaction stores its currency
  • Filter and sort by currency
  • Currency conversion (requires currency API)
Currency exchange rates are fetched from the configured currency API service.

​
Database Schema

Transactions are stored with the following structure: 
create table transactions (
  id uuid primary key default gen_random_uuid(),
  amount numeric(10, 2) default 0,
  currency varchar(3) default 'usd',
  user_id text references users (id) on delete cascade,
  organization_id text references organizations (id) on delete cascade,
  external_id varchar(255),
  category_id uuid references categories (id) on delete set null,
  reference_no varchar(255),
  name varchar(255),
  description varchar(1000),
  status varchar(8) default 'paid',
  source varchar(255) default 'manual',
  metadata jsonb,
  transaction_date timestamp default current_timestamp,
  created_at timestamp default current_timestamp,
  updated_at timestamp default current_timestamp
);

​
Row-Level Security

Transactions are protected by PostgreSQL row-level security policies:
  • Users can only access their own transactions
  • Organization members can access shared transactions based on their role
  • Different policies for SELECT, INSERT, UPDATE, and DELETE operations

​
API Access

Access transactions programmatically using the PostgREST API: 
// Get all transactions
const { data } = await client
  .from('transactions')
  .select('*')
  .order('transaction_date', { ascending: false });

// Create a transaction
const { data, error } = await client
  .from('transactions')
  .insert({
    name: 'Coffee',
    amount: -4.50,
    currency: 'USD',
    transaction_date: new Date().toISOString(),
    category_id: 'uuid-here',
    status: 'paid'
  });

​
Best Practices

Regular Entry

Enter transactions regularly (daily or weekly) to maintain accurate records.

Use Categories

Always categorize transactions for better reporting and analysis.

Add Descriptions

Include descriptions for complex or important transactions.

Regular Exports

Export your data regularly for backup purposes.

​
Troubleshooting

  • Check active filters - you may be filtering it out
  • Verify the transaction date is within your view range
  • Ensure you have the correct organization selected (if using organizations)
  • Check your organization role - viewers cannot edit
  • Ensure you’re not in view-only mode
  • Refresh the page and try again
  • Verify your file format is correct
  • Check that all required fields are present
  • Ensure dates are in ISO format (YYYY-MM-DD)
  • Verify currency codes are valid 3-letter codes

Build docs developers (and LLMs) love

Get started for freeTalk to us