Skip to main content

Transaction Management

OneLibro's transaction management system provides comprehensive tools to view, filter, search, and export your financial transaction history. Transactions are automatically synced from your connected bank accounts via Plaid and can also be added manually.

Overview​

The transaction management feature allows you to:

  • View complete transaction history from all connected accounts
  • Filter by date range (Last 7/30/90/365 days, or All time)
  • Search by merchant name to quickly find specific transactions
  • Filter by category to analyze spending in specific areas
  • Export to CSV for external analysis or record-keeping
  • Add manual transactions for cash purchases or accounts not connected via Plaid
  • Track pending vs posted status for accurate balance calculations
  • Responsive design with table view (desktop) and card view (mobile)

Accessing Transactions​

  1. Log in to your OneLibro account
  2. Go to Transactions from the main navigation menu
  3. The transactions page loads your most recent 30 days of transactions by default

Page URL​

/finance/transactions

Viewing Transactions​

Desktop View (Table Layout)​

On larger screens, transactions are displayed in a data table with columns:

ColumnDescription
DateTransaction date (formatted as MMM DD, YYYY)
MerchantBusiness or individual name
CategoryTransaction category (from Plaid or manual entry)
AmountTransaction amount (red for expenses, green for income)
StatusPending or Posted

Features:

  • Sortable columns (coming soon)
  • Hover effect highlights row
  • Clean, scannable layout
  • Fixed header for scrolling large lists

Mobile View (Card Layout)​

On mobile devices, transactions appear as cards with:

  • Top Section: Merchant name and date
  • Right Side: Amount (large, bold, color-coded)
  • Bottom Section: Category badge and status badge

Benefits:

  • Touch-friendly design
  • Easy-to-scan cards
  • Swipe-friendly scrolling
  • All information visible at a glance

Filtering Transactions​

Date Range Filter​

Filter transactions by time period to focus on relevant data.

Available Options:

  • Last 7 days: Recent weekly spending
  • Last 30 days: Current month's activity (default)
  • Last 90 days: Quarterly analysis
  • Last year: Annual spending patterns
  • All time: Complete transaction history

How It Works:

// Date calculation example
const daysAgo = 30; // For "Last 30 days"
const startDate = new Date();
startDate.setDate(startDate.getDate() - daysAgo);

// Fetches transactions where transaction_date >= startDate

Use Cases:

  • Last 7 days: Check recent spending before paycheck
  • Last 30 days: Month-end budget review
  • Last 90 days: Identify seasonal spending trends
  • Last year: Tax preparation or annual analysis
  • All time: Find old transactions for warranties or returns

Category Filter​

Filter transactions to show only specific categories.

How It Works:

  1. Categories are dynamically extracted from your transactions
  2. Dropdown shows all unique categories in alphabetical order
  3. Select "All Categories" to see everything
  4. Select a specific category to filter

Category Examples:

  • Food and Drink
  • Groceries
  • Shopping
  • Transportation
  • Travel
  • Entertainment
  • Bills & Utilities
  • Healthcare
  • Uncategorized (for transactions without a category)

Use Cases:

  • Budget tracking: View all "Groceries" transactions for the month
  • Tax preparation: Filter "Healthcare" or "Home" expenses
  • Spending analysis: Compare "Entertainment" vs "Food and Drink"
  • Reimbursement: Find all work-related "Travel" expenses

Search by Merchant​

Search for transactions by merchant name using the search bar.

Search Features:

  • Case-insensitive: Searches work regardless of capitalization
  • Partial matching: "starbucks" finds "Starbucks Coffee #1234"
  • Real-time filtering: Results update as you type
  • Works with other filters: Search combines with date and category filters

Search Examples:

  • Search "amazon" → finds all Amazon purchases
  • Search "Shell" → finds gas station purchases
  • Search "ATM" → finds cash withdrawals
  • Search "Target" → finds all Target transactions

Tips:

  • Use short, common terms (e.g., "star" instead of "starbucks coffee")
  • Remove special characters if not finding results
  • Try different variations of merchant names
  • Clear search to see all transactions again

Combining Filters​

All filters work together to narrow down your transaction list.

Example Use Case: Find entertainment spending last month

  1. Set date filter: "Last 30 days"
  2. Set category filter: "Entertainment"
  3. Optionally search for specific merchant (e.g., "Netflix")
  4. View filtered results showing only matching transactions

Filter Logic:

Displayed Transactions = All Transactions
  WHERE date >= startDate
  AND category = selectedCategory (if not "all")
  AND merchant_name CONTAINS searchQuery

Transaction Details​

Transaction Fields​

Each transaction contains the following information:

From Plaid (Automatic):

  • transaction_date: Date the transaction occurred
  • merchant_name: Business or merchant name
  • amount: Transaction amount in cents (positive = expense, negative = income)
  • category: Primary category from Plaid
  • is_pending: Whether transaction is pending or posted
  • plaid_transaction_id: Unique identifier from Plaid
  • account_id: Which account this transaction belongs to

User-Added (Manual Transactions):

  • user_notes: Custom notes or descriptions
  • Custom category overrides (if applicable)

Transaction Status​

Pending Transactions:

  • Shown with yellow "Pending" badge
  • Have been authorized but not yet settled
  • Amount may change slightly when posted
  • Not final - can still be canceled or adjusted
  • Typically post within 1-3 business days

Posted Transactions:

  • Shown with green "Posted" badge
  • Fully settled and finalized
  • Amount is locked in
  • Cannot be changed or canceled
  • Used for final balance calculations

Status in UI:

{transaction.is_pending ? (
  <span className="bg-yellow-900/30 text-yellow-300 rounded-full text-xs">
    Pending
  </span>
) : (
  <span className="bg-green-900/30 text-green-300 rounded-full text-xs">
    Posted
  </span>
)}

Income vs Expenses​

Transactions are color-coded based on type:

Expenses (Positive Amount):

  • Displayed in red with minus sign
  • Example: -$45.67
  • Reduces your account balance
  • Most common transaction type

Income (Negative Amount):

  • Displayed in green with plus sign
  • Example: +$1,500.00
  • Increases your account balance
  • Includes: paychecks, refunds, transfers in
Amount Convention

OneLibro follows Plaid's convention where positive amounts are expenses and negative amounts are income. This may seem counterintuitive, but it's standard in banking systems.

Exporting Transactions​

Export to CSV​

Download your transactions as a CSV file for use in Excel, Google Sheets, or other financial software.

How to Export:

  1. Apply desired filters (date, category, search)
  2. Click the "Export" button (top-right of page)
  3. CSV file downloads automatically
  4. Open in spreadsheet application

CSV Format:

Date,Merchant,Category,Amount,Status,Account,Notes
2025-01-15,Starbucks,Food and Drink,$5.47,Posted,Checking,
2025-01-14,Amazon.com,Shopping,$32.15,Posted,Credit Card,Work supplies

CSV Columns:

  • Date (formatted as YYYY-MM-DD for sorting)
  • Merchant
  • Category
  • Amount (formatted as currency with $ sign)
  • Status (Pending/Posted)
  • Account (account name)
  • Notes (user notes, if any)

Export Use Cases​

Tax Preparation:

  1. Set date filter to last year (January 1 - December 31)
  2. Filter by tax-deductible categories (Healthcare, Home, etc.)
  3. Export to CSV
  4. Share with accountant or import to tax software

Budget Analysis:

  1. Export last 90 days
  2. Open in Excel/Sheets
  3. Create pivot tables to analyze spending by category
  4. Generate custom charts and reports

Expense Reimbursement:

  1. Filter by date range (e.g., business trip dates)
  2. Search for relevant merchants (hotels, airlines, etc.)
  3. Export filtered transactions
  4. Submit for reimbursement with CSV as proof

Record Keeping:

  1. Export all transactions monthly
  2. Save CSV files for your records
  3. Keep offline backup of financial history
  4. Useful for audits or disputes

Adding Manual Transactions​

Sometimes you need to record transactions that don't sync automatically from Plaid (e.g., cash purchases, Venmo payments, split bills).

When to Add Manual Transactions​

  • Cash purchases: Bought coffee with cash
  • P2P payments: Venmo, Cash App, Zelle transfers
  • Checks: Wrote or deposited a check
  • Temporary record: Account not yet linked via Plaid
  • Custom categorization: Override Plaid's categorization

How to Add a Transaction​

Navigation:

  1. Go to Transactions page
  2. Click "Add" button (top-right, or from empty state)
  3. Fill out the transaction form
  4. Click "Add Transaction"

Form Fields:

Date (Required):

  • Date the transaction occurred
  • Format: Date picker or manual entry
  • Can be past, present, or future (for scheduled transactions)

Merchant (Required):

  • Name of business or person
  • Examples: "Corner Store", "John (rent)", "Gas Station"

Amount (Required):

  • Transaction amount in dollars
  • Use positive numbers for expenses
  • Use negative numbers for income (or toggle switch if available)
  • Examples: 25.50, 150.00

Category (Required):

  • Select from predefined categories or create custom
  • Used for budget tracking and analysis

Account (Required):

  • Which account this transaction should be associated with
  • Select from your connected accounts or "Cash"

Notes (Optional):

  • Additional context or details
  • Examples: "Split dinner with Sarah", "Work expense", "Gift for Mom"

Manual Transaction Example​

// Example manual transaction creation
{
  user_id: "user-uuid",
  transaction_date: "2025-01-20",
  merchant_name: "Joe's Coffee",
  amount: 475, // $4.75 in cents
  category: "Food and Drink",
  account_id: "account-uuid",
  user_notes: "Meeting coffee",
  is_pending: false,
  is_manual: true, // Flag for manual entry
}

Empty States​

No Transactions at All​

If you haven't connected any accounts or added transactions:

  • Friendly message: "No transactions yet"
  • Two call-to-action buttons:
    • "Add Transaction" → Manual entry
    • "Connect Bank" → Link accounts via Plaid

No Results After Filtering​

If your filters don't match any transactions:

  • Message: "No transactions found"
  • Suggestion: "Try adjusting your filters or search query"
  • Search icon displayed
  • Filters remain active for easy adjustment

Transaction Sync​

Automatic Syncing​

Transactions sync automatically from Plaid in these scenarios:

  • Initial connection: All recent transactions (up to 2 years) sync
  • Daily sync: OneLibro automatically fetches new transactions daily
  • Manual sync: Triggered from the Accounts page
Sync Frequency

Plaid typically updates transactions every 6-24 hours. Sync manually before important budget reviews to ensure you have the latest data.

How Transactions Are Synced​

Plaid Transactions API:

  1. OneLibro requests transactions since last sync
  2. Plaid returns new/updated transactions with cursor
  3. Transactions are inserted into database
  4. Cursor is saved for next sync
  5. Process repeats to get all new transactions

Sync Details:

  • Uses cursor-based pagination (no duplicates)
  • Syncs up to 500 transactions per page
  • Handles transaction updates (pending → posted)
  • Removes duplicate transactions automatically

Transaction Matching:

  • Each transaction has unique plaid_transaction_id
  • If ID already exists, transaction is updated (not duplicated)
  • Prevents showing same transaction twice

Responsive Design​

Desktop (768px+)​

  • Table layout with sortable columns
  • Multiple transactions visible at once
  • Filters always visible
  • Export and Add buttons in header

Tablet (768px - 1024px)​

  • Compressed table or card hybrid
  • Filters collapsible
  • Touch-friendly buttons

Mobile (<768px)​

  • Card layout for better touch experience
  • Filters hidden behind collapsible panel
  • Large tap targets (buttons, filters)
  • Swipe-friendly scrolling
  • Condensed "Add" and "Export" button text

Performance Considerations​

Transaction Limits​

Default Query:

  • Fetches 500 most recent transactions
  • Adjust with date filters to reduce query size

Large Datasets:

  • If you have 1,000+ transactions, use filters to narrow results
  • Export feature handles large datasets efficiently
  • Frontend pagination (coming soon) will improve performance

Loading States​

Initial Load:

  • Spinner with "Loading transactions..." message
  • Prevents interaction until data is ready

Filter Changes:

  • Instant client-side filtering (no re-fetch needed)
  • Search and category filters are applied to already-loaded transactions
  • Only date filter triggers new database query

API Reference​

Fetching Transactions​

import { getUserTransactions } from '@/lib/supabase';

// Fetch transactions with filters
const transactions = await getUserTransactions(userId, {
  limit: 500,
  startDate: '2025-01-01T00:00:00Z', // ISO format
  endDate: '2025-01-31T23:59:59Z',
});

Parameters:

  • userId (string): User's unique ID
  • options (object):
    • limit (number): Max transactions to return (default: 100)
    • startDate (string, optional): ISO 8601 timestamp
    • endDate (string, optional): ISO 8601 timestamp

Returns:

  • Array of Transaction objects sorted by date (newest first)

Transaction Type​

interface Transaction {
  id: string;
  user_id: string;
  account_id: string;
  plaid_transaction_id?: string; // Only for Plaid transactions
  transaction_date: string; // ISO 8601 format
  merchant_name: string | null;
  amount: number; // In cents (positive = expense, negative = income)
  category: string | null;
  is_pending: boolean;
  user_notes: string | null;
  created_at: string;
  updated_at: string;
}

Export Function​

import { exportTransactionsToCSV } from '@/lib/export';

// Export transactions to CSV file
exportTransactionsToCSV(filteredTransactions);

// Generates CSV and triggers browser download
// Filename format: transactions_YYYY-MM-DD.csv

Best Practices​

Review Frequency​

Daily Quick Check (2 minutes):

  • Glance at last 7 days
  • Identify any unauthorized transactions
  • Verify pending transactions posted correctly

Weekly Review (10 minutes):

  • Check last 30 days
  • Categorize uncategorized transactions
  • Compare to weekly budgets
  • Add notes for unusual purchases

Monthly Deep Dive (30 minutes):

  • Export month's transactions
  • Analyze spending by category
  • Compare to monthly budgets
  • Identify areas to cut spending

Categorization Strategy​

Let Plaid Do the Work:

  • Most transactions are auto-categorized accurately
  • Only recategorize if clearly wrong

Common Miscategorizations:

  • Online marketplaces (Amazon) → Often "Shopping" but could be "Groceries", "Electronics", etc.
  • Warehouse stores (Costco, Sam's Club) → Often "Shopping" but could be "Groceries"
  • Gas stations → "Transportation" if gas, "Food and Drink" if convenience store

Fix Miscategorizations:

  • Add notes to clarify (e.g., "Amazon - groceries")
  • Use filters to group similar purchases
  • Manual transactions let you set exact category

Search Tips​

Be Specific:

  • ✅ "starbucks" → finds all Starbucks purchases
  • ❌ "coffee" → might miss Starbucks if merchant is "Starbucks Coffee #1234"

Use Partial Names:

  • ✅ "target" → finds "Target Store #1234", "Target.com", etc.
  • ✅ "uber" → finds "Uber Trip", "Uber Eats", etc.

Remember Merchant Formatting:

  • Credit cards often add numbers: "Shell Oil #12345"
  • Online purchases may include domain: "Amazon.com"
  • Recurring subscriptions may include reference numbers

Export Best Practices​

Regular Backups:

  • Export all transactions quarterly
  • Save CSV files locally or in cloud storage
  • Provides offline backup of financial history

Tax Season:

  • Export full year in early January
  • Filter by tax-deductible categories
  • Share with accountant or use for tax software

Large Exports:

  • For 1,000+ transactions, use date filters to break into chunks
  • Multiple smaller exports perform better than one massive export
  • Combine CSV files later if needed

Troubleshooting​

Transaction Not Appearing​

Possible Causes:

  1. Not synced yet: Plaid hasn't updated
  2. Outside date filter: Transaction is older than selected range
  3. Wrong account: Transaction is on non-connected account
  4. Pending: Very recent transaction still pending

Solutions:

  • Go to Accounts → Sync Transactions manually
  • Change date filter to "All time"
  • Check if account is connected
  • Wait 24-48 hours for pending transactions to appear

Duplicate Transactions​

Should Not Happen: OneLibro prevents duplicates using plaid_transaction_id

If It Does:

  • Report bug to support
  • Likely caused by manual transaction with same details as synced transaction
  • Delete manual transaction if duplicate of synced one

Wrong Transaction Amount​

Pending Transactions:

  • Amounts can change when pending → posted
  • Example: Gas station pre-auth ($50) → actual charge ($42.15)
  • Wait for transaction to post for final amount

Posted Transactions:

  • Should match your bank statement exactly
  • If wrong, re-sync transactions from Accounts page
  • If still wrong, report to support (may be Plaid issue)

Cannot Find Transaction​

Search Not Working:

  1. Clear search and try again
  2. Check spelling of merchant name
  3. Try partial name (e.g., "star" instead of "starbucks")
  4. Use category filter instead of search

Transaction Definitely Missing:

  1. Check date filter (set to "All time")
  2. Verify account is connected
  3. Sync transactions manually
  4. Check your bank - transaction might be pending or denied
  • Accounts - Connect and manage bank accounts
  • Budgets - Track spending against budgets
  • Dashboard - Visual overview of finances
  • Plaid Integration Guide (coming in Phase 2) - Developer guide for Plaid

Summary​

Transaction management in OneLibro provides:

  • ✅ Complete transaction history from all accounts
  • ✅ Powerful filtering (date, category, search)
  • ✅ Export to CSV for external analysis
  • ✅ Manual transaction entry
  • ✅ Pending vs Posted status tracking
  • ✅ Responsive design (desktop table, mobile cards)
  • ✅ Automatic syncing from Plaid
  • ✅ Color-coded income vs expenses

Use the Transactions page daily to stay on top of your finances, weekly to review spending patterns, and monthly for deep budget analysis!