Skip to main content

​
Overview

Transactions are the core of Your Finance App. Every income, expense, or transfer is recorded as a transaction, allowing you to track your financial activity across all your accounts.

Multi-Currency Support

Track transactions in ARS, USD, and EUR with automatic currency enforcement

Smart Categorization

Organize transactions with flexible categories for better insights

Soft Delete

Deleted transactions can be recovered and don’t break your balance history

Balance Tracking

Real-time balance updates across all accounts and currencies

​
Transaction Types

Your Finance App supports three types of transactions:
  • INCOME: Money coming into your accounts (salary, gifts, refunds)
  • EXPENSE: Money going out of your accounts (purchases, bills, fees)
  • TRANSFER: Moving money between your own accounts

​
Creating a Transaction

To create a transaction, send a POST request to /transactions: 
{
  "type": "EXPENSE",
  "amount": 1500.75,
  "description": "Grocery shopping",
  "categoryId": "uuid-of-category",
  "accountId": "uuid-of-account",
  "date": "2026-03-04T14:30:00.000Z"
}

​
Request Parameters

​
type
enum
required
Transaction type: INCOME, EXPENSE, or TRANSFER
​
amount
number
required
Transaction amount (must be greater than 0, up to 2 decimal places)
​
accountId
string
required
UUID of the account where this transaction occurs
​
description
string
Optional description (max 500 characters)
​
categoryId
string
Optional UUID of the category for organization
​
date
string
Optional ISO date string (defaults to current time)
​
currency
string
Optional currency code (ARS, USD, EUR). Must match account currency
Automatic Currency Validation: The transaction currency must match the account’s currency. If you try to create a USD transaction on an ARS account, you’ll receive an error.

​
Balance Protection

Your Finance App includes overdraft protection. When creating an expense or transfer, the system validates that you have sufficient funds: 
// ❌ This will fail if your balance is less than $2000
{
  "type": "EXPENSE",
  "amount": 2000.00,
  "accountId": "account-with-1500-balance"
}
Error response: 
{
  "statusCode": 400,
  "message": "Fondos insuficientes. Tu saldo es $1500.00 y intentas gastar $2000.00"
}

​
Filtering Transactions

Retrieve transactions with powerful filtering options: 
GET /transactions?page=1&limit=20&type=EXPENSE&month=3&year=2026
  • page (number): Page number for pagination (default: 1)
  • limit (number): Results per page (default: 20)
  • type (enum): Filter by INCOME, EXPENSE, or TRANSFER
  • accountId (string): Filter by specific account
  • categoryId (string): Filter by specific category
  • startDate (string): ISO date for range start
  • endDate (string): ISO date for range end
  • month (number): Filter by month (1-12)
  • year (number): Filter by year
  • search (string): Search in description or category name

​
Response Format

Transactions are returned with pagination: 
{
  "data": [
    {
      "id": "uuid",
      "type": "EXPENSE",
      "amount": 1500.75,
      "description": "Grocery shopping",
      "date": "2026-03-04T14:30:00.000Z",
      "currency": "ARS",
      "category": {
        "id": "uuid",
        "name": "Food & Dining",
        "color": "#10B981",
        "icon": "utensils"
      },
      "account": {
        "id": "uuid",
        "name": "Main Wallet",
        "type": "WALLET"
      }
    }
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 20,
    "totalPages": 8
  }
}

​
Calculating Your Balance

Get your current balance across all accounts, grouped by currency: 
GET /transactions/balance
Response: 
{
  "netWorth": {
    "ARS": 125000.50,
    "USD": 3500.00,
    "EUR": 1200.00
  }
}

​
Updating Transactions

Update an existing transaction with PATCH /transactions/:id: 
{
  "amount": 1600.00,
  "description": "Updated grocery total",
  "categoryId": "new-category-uuid"
}
Balance Recalculation: When you update a transaction, the system automatically:
  1. Reverts the old transaction’s impact on the account balance
  2. Applies the new transaction values
  3. Updates the account balance accordingly
This ensures your balances always remain accurate.

​
Category Validation

The system validates that transaction types match their categories:
  • An INCOME transaction can only use categories of type INCOME or BOTH
  • An EXPENSE transaction can only use categories of type EXPENSE or BOTH
  • TRANSFER transactions automatically use the “Transferencia” category

​
Soft Delete

Deleting a transaction marks it as deleted without removing it from the database: 
DELETE /transactions/:id
Response: 
{
  "message": "Transacción eliminada y saldo restaurado."
}
Soft-deleted transactions:
  • Are excluded from queries and reports
  • Have their balance impact reversed
  • Maintain referential integrity in your database
  • Can be recovered by support if needed

​
Best Practices

While categories are optional, they’re essential for budgeting and reporting. Make it a habit to categorize every transaction.
Clear descriptions help you remember transactions months later. “Starbucks” is better than “Coffee”.
Each account has one currency. To convert between currencies, use transfers between accounts with different currencies (future feature).
Use the /transactions/balance endpoint regularly to track your net worth across currencies.

​
Common Workflows

​
Recording a Salary Payment

POST /transactions
{
  "type": "INCOME",
  "amount": 150000.00,
  "description": "Monthly salary - March 2026",
  "categoryId": "salary-category-uuid",
  "accountId": "main-wallet-uuid",
  "currency": "ARS"
}

​
Recording a Monthly Expense

POST /transactions
{
  "type": "EXPENSE",
  "amount": 45000.00,
  "description": "Rent for March",
  "categoryId": "rent-category-uuid",
  "accountId": "main-wallet-uuid"
}

​
Searching Transactions

# Find all transactions containing "uber" or in a category containing "uber"
GET /transactions?search=uber

# Find all expenses in March 2026
GET /transactions?type=EXPENSE&month=3&year=2026

# Find transactions in a date range
GET /transactions?startDate=2026-03-01&endDate=2026-03-31

Build docs developers (and LLMs) love

Get started for freeTalk to us