Skip to main content

​
Overview

A Transaction represents any financial activity — money coming in (income) or going out (expense). Transactions are linked to both a wallet and optionally a category.

​
Transaction Properties

PropertyTypeDescription
idStringLocal UUID (primary key)
serverIdString?Server-assigned ID after sync
walletIdStringAssociated wallet ID
categoryIdString?Optional category ID
amountdoubleTransaction amount (always positive)
typeStringincome, expense, or transfer
descriptionString?Optional description
dateDateTimeWhen the transaction occurred
syncStatusSyncStatusCurrent sync state

​
Transaction Types

​
Income

Money coming into a wallet: 
final income = await cache.createTransaction(
  walletId: walletId,
  categoryId: salaryCategoryId,
  amount: 5000.00,
  type: 'income',
  description: 'Monthly salary',
  date: DateTime.now(),
);

​
Expense

Money leaving a wallet: 
final expense = await cache.createTransaction(
  walletId: walletId,
  categoryId: foodCategoryId,
  amount: 25.50,
  type: 'expense',
  description: 'Lunch with colleagues',
  date: DateTime.now(),
);

​
Transfer

Moving money between wallets: 
// Create two transactions: expense from source, income to destination
final transferOut = await cache.createTransaction(
  walletId: sourceWalletId,
  amount: 100.00,
  type: 'expense',
  description: 'Transfer to savings',
);

final transferIn = await cache.createTransaction(
  walletId: destWalletId,
  amount: 100.00,
  type: 'income',
  description: 'Transfer from checking',
);

​
Creating Transactions

​
Using the Cache Manager

final cache = CacheManager.instance;

final transaction = await cache.createTransaction(
  walletId: wallet.id,
  categoryId: category?.id,
  amount: 45.67,
  type: 'expense',
  description: 'Grocery shopping',
  date: DateTime.now(),
);

​
Direct Repository Access

final transaction = Transaction(
  id: cache.generateId(),
  walletId: walletId,
  categoryId: categoryId,
  amount: 99.99,
  type: 'expense',
  description: 'Monthly subscription',
  date: DateTime(2024, 1, 15),
  createdAt: DateTime.now(),
  updatedAt: DateTime.now(),
);

await cache.transactions.save(transaction);

​
Querying Transactions

​
Get All Transactions

final transactions = await cache.transactions.findAll();

​
Filter by Wallet

final walletTransactions = await cache.transactions.findByWallet(walletId);

​
Filter by Date Range

// Get this month's transactions
final now = DateTime.now();
final startOfMonth = DateTime(now.year, now.month, 1);

final monthlyTransactions = await cache.transactions.findByDateRange(
  startOfMonth,
  now,
);

// Get transactions for specific wallet in date range
final walletMonthlyTransactions = await cache.transactions.findByDateRange(
  startOfMonth,
  now,
  walletId: walletId,
);

​
Get Pending Sync

final pending = await cache.transactions.findPendingSync();

​
Calculating Totals

// Get all transactions for a wallet
final transactions = await cache.transactions.findByWallet(walletId);

// Calculate totals
double income = 0;
double expenses = 0;

for (final t in transactions) {
  if (t.type == 'income') {
    income += t.amount;
  } else if (t.type == 'expense') {
    expenses += t.amount;
  }
}

final net = income - expenses;
print('Net: $net');  // Net cash flow

​
Updating Transactions

final transaction = await cache.transactions.findById(transactionId);
if (transaction != null) {
  final updated = transaction.copyWith(
    amount: 50.00,  // Corrected amount
    description: 'Updated description',
  );
  await cache.transactions.save(updated);
}

​
Deleting Transactions

// Soft delete
await cache.transactions.delete(transactionId);

// Hard delete
await cache.transactions.delete(transactionId, hardDelete: true);

​
Best Practices

  1. Be specific with descriptions - “Lunch at Chipotle” > “Food”
  2. Record immediately - Log transactions while memory is fresh
  3. Use categories consistently - Don’t mix similar categories
  4. Review weekly - Catch errors early
  • Wallets - Where transactions occur
  • Categories - How transactions are organized
  • Sync - How transactions sync across devices