> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeus.ttr.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Transactions

> Recording financial activity

## 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

| Property      | Type       | Description                          |
| ------------- | ---------- | ------------------------------------ |
| `id`          | String     | Local UUID (primary key)             |
| `serverId`    | String?    | Server-assigned ID after sync        |
| `walletId`    | String     | Associated wallet ID                 |
| `categoryId`  | String?    | Optional category ID                 |
| `amount`      | double     | Transaction amount (always positive) |
| `type`        | String     | `income`, `expense`, or `transfer`   |
| `description` | String?    | Optional description                 |
| `date`        | DateTime   | When the transaction occurred        |
| `syncStatus`  | SyncStatus | Current sync state                   |

## Transaction Types

### Income

Money coming into a wallet:

```dart theme={null}
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:

```dart theme={null}
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:

```dart theme={null}
// 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

```dart theme={null}
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

```dart theme={null}
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

```dart theme={null}
final transactions = await cache.transactions.findAll();
```

### Filter by Wallet

```dart theme={null}
final walletTransactions = await cache.transactions.findByWallet(walletId);
```

### Filter by Date Range

```dart theme={null}
// 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

```dart theme={null}
final pending = await cache.transactions.findPendingSync();
```

## Calculating Totals

```dart theme={null}
// 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

```dart theme={null}
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

```dart theme={null}
// 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

## Related

* [Wallets](/concepts/wallets) - Where transactions occur
* [Categories](/concepts/categories) - How transactions are organized
* [Sync](/concepts/sync) - How transactions sync across devices