Your First Transaction

Recording your first transaction is a milestone! This guide will walk you through creating a simple transaction, explain how credits are consumed, and help you understand the cost implications of different operations.

Prerequisites

Before recording transactions, you should have:

• ✅ Organization Created: Master organization with API access
• ✅ API Key Generated: Live or test key for authentication
• ✅ Basic Accounts Set Up: At least cash and revenue accounts
• ✅ Credits Available: Check your balance before proceeding

Understanding Credit Consumption

How Credits Work

Every API operation consumes credits from your organization's pool:

Example Costs:

• List accounts: 0 credits (free)
• Create account: 1 credit ($0.01)
• Record transaction: 2 credits ($0.02)
• Generate report: 5 credits ($0.05)

Check Your Balance

Always check credits before operations:

GET /organizations/{org_id}/billing
Authorization: Bearer cl_live_your_key

{
  "credits_remaining": 485,
  "credits_total": 500,
  "auto_recharge_enabled": true
}

Cost Awareness Tip: With 485 credits remaining, you can perform ~240 simple operations before needing more credits.

Step 1: Review Your Accounts

List Current Accounts

Check what accounts you have available:

GET /organizations/org_1234567890abcdef/accounts
Authorization: Bearer cl_live_your_key

Example Response:

[
  {
    "id": "act_1234567890abcdef",
    "code": "1001",
    "name": "Operating Cash",
    "type": "asset"
  },
  {
    "id": "act_2345678901bcdef0",
    "code": "4001",
    "name": "Sales Revenue",
    "type": "revenue"
  }
]

Cost: 0 credits (free)

Step 2: Plan Your Transaction

Transaction Basics

Every transaction must:

• ✅ Balance: Total debits = Total credits
• ✅ Have a description: Clear explanation of the business event
• ✅ Include dates: When the transaction occurred
• ✅ Reference accounts: Valid account IDs

Simple Cash Sale Transaction

Business Event: You sold $250 worth of products for cash.

Accounting Impact:

• Cash increases (debit cash account)
• Revenue increases (credit revenue account)

Double-Entry:

Debit  Cash (Asset)           $250.00  ← Money coming in
Credit Sales Revenue          $250.00  ← Income earned

Step 3: Record the Transaction

Create Transaction

POST /organizations/org_1234567890abcdef/transactions
Authorization: Bearer cl_live_your_key
Content-Type: application/json

{
  "description": "Cash sale - Product ABC",
  "transaction_date": "2024-01-15",
  "entries": [
    {
      "account_id": "act_1234567890abcdef",
      "entry_type": "debit",
      "amount": 250.00,
      "description": "Cash received from customer"
    },
    {
      "account_id": "act_2345678901bcdef0",
      "entry_type": "credit",
      "amount": 250.00,
      "description": "Revenue from product sale"
    }
  ]
}

Cost: 2 credits ($0.02)

What happens:

• Transaction is validated for balance
• Account balances are updated
• Audit trail entry is created
• Credits are deducted from your balance

Step 4: Verify the Transaction

Check Transaction Details

GET /organizations/org_1234567890abcdef/transactions/txn_1234567890abcdef
Authorization: Bearer cl_live_your_key

Response:

{
  "id": "txn_1234567890abcdef",
  "description": "Cash sale - Product ABC",
  "status": "posted",
  "transaction_date": "2024-01-15",
  "posting_date": "2024-01-15T10:30:00Z",
  "total_debits": 250.00,
  "total_credits": 250.00,
  "entries": [
    {
      "account_id": "act_1234567890abcdef",
      "entry_type": "debit",
      "amount": 250.00,
      "description": "Cash received from customer"
    },
    {
      "account_id": "act_2345678901bcdef0",
      "entry_type": "credit",
      "amount": 250.00,
      "description": "Revenue from product sale"
    }
  ]
}

Cost: 0 credits (free)

Verify Account Balances

Check that balances updated correctly:

GET /organizations/org_1234567890abcdef/accounts
Authorization: Bearer cl_live_your_key

Response:

[
  {
    "id": "act_1234567890abcdef",
    "code": "1001",
    "name": "Operating Cash",
    "type": "asset",
    "balance": {
      "debit": 250.00,
      "credit": 0.00,
      "net": 250.00  // Asset balance increased ✓
    }
  },
  {
    "id": "act_2345678901bcdef0",
    "code": "4001",
    "name": "Sales Revenue",
    "type": "revenue",
    "balance": {
      "debit": 0.00,
      "credit": 250.00,
      "net": 250.00  // Revenue balance increased ✓
    }
  }
]

Cost: 0 credits (free)

Step 5: Understanding the Impact

Accounting Equation Check

Assets = Liabilities + Equity + Revenue - Expenses

Before transaction: $0 = $0 + $0 + $0 - $0 ✅

After transaction: $250 = $0 + $0 + $250 - $0 ✅

The equation still balances! This is the power of double-entry bookkeeping.

Financial Position

Your business position improved:

• Cash increased by $250 (positive cash flow)
• Revenue increased by $250 (income earned)
• Net worth increased by $250 (retained earnings)

Cost Analysis

Credits Used So Far

Scaling to Business Volume

Daily Operations (50 transactions):

• Transactions: 50 × 2 credits = 100 credits ($1.00)
• Balance checks: 20 × 0 credits = 0 credits (free)
• Reports: 5 × 5 credits = 25 credits ($0.25)
• Daily Total: 125 credits ($1.25)

Monthly Operations (22 business days):

• 22 × 125 credits = 2,750 credits ($27.50)
• Plus base cost: $1.00
• Monthly Total: ~$28.54

Annual Operations:

• 12 × $28.54 = $342.48
• Cost per transaction: ~$0.014 (very cost-effective!)

Common Transaction Patterns

Cash Sales (What we just did)

{
  "description": "Cash sale",
  "entries": [
    {"account_id": "cash", "entry_type": "debit", "amount": 100.00},
    {"account_id": "sales_revenue", "entry_type": "credit", "amount": 100.00}
  ]
}

Credit Sales

{
  "description": "Credit sale - Invoice #001",
  "entries": [
    {"account_id": "accounts_receivable", "entry_type": "debit", "amount": 500.00},
    {"account_id": "sales_revenue", "entry_type": "credit", "amount": 500.00}
  ]
}

Cash Payment

{
  "description": "Rent payment",
  "entries": [
    {"account_id": "rent_expense", "entry_type": "debit", "amount": 1200.00},
    {"account_id": "cash", "entry_type": "credit", "amount": 1200.00}
  ]
}

Owner Investment

{
  "description": "Owner capital contribution",
  "entries": [
    {"account_id": "cash", "entry_type": "debit", "amount": 10000.00},
    {"account_id": "owner_capital", "entry_type": "credit", "amount": 10000.00}
  ]
}

Error Handling

Common Transaction Errors

"Transaction does not balance"

{
  "error": "validation_error",
  "message": "Transaction does not balance",
  "details": {
    "total_debits": 150.00,
    "total_credits": 100.00,
    "difference": 50.00
  }
}

Fix: Ensure debits equal credits exactly.

"Account not found"

{
  "error": "validation_error",
  "message": "Account act_invalid_id does not exist"
}

Fix: Use valid account IDs from your chart of accounts.

"Insufficient credits"

{
  "error": "credit_limit_error",
  "message": "Insufficient credits remaining",
  "details": {
    "required": 2,
    "available": 1
  }
}

Fix: Purchase more credits or enable auto-recharge.

Testing with Free Credits

Use test keys for development:

# Test key - operations use mock credits
Authorization: Bearer cl_test_your_test_key

# Live key - operations use real credits
Authorization: Bearer cl_live_your_live_key

Best Practices

Transaction Recording

1. Record immediately - Enter transactions when business events occur
2. Use clear descriptions - Explain what happened and why
3. Include references - Invoice numbers, check numbers, customer names
4. Verify balances - Check account balances after recording

Cost Optimization

1. Batch operations - Group similar transactions when possible
2. Use read operations freely - They're completely free (0 credits)
3. Cache data - Reduce repeated API calls for write operations
4. Monitor usage - Track your credit consumption patterns

Quality Assurance

1. Review transactions - Double-check amounts and accounts
2. Test with small amounts - Verify logic before large transactions
3. Keep audit trails - Document your business reasoning
4. Reconcile regularly - Match to bank statements and external records

Advanced Transaction Types

Multi-Entry Transactions

{
  "description": "Payroll with taxes and deductions",
  "entries": [
    {"account_id": "salaries_expense", "entry_type": "debit", "amount": 3000.00},
    {"account_id": "payroll_taxes_expense", "entry_type": "debit", "amount": 450.00},
    {"account_id": "cash", "entry_type": "credit", "amount": 2550.00},
    {"account_id": "payroll_taxes_payable", "entry_type": "credit", "amount": 450.00},
    {"account_id": "salaries_payable", "entry_type": "credit", "amount": 450.00}
  ]
}

Reversing Transactions

// Original transaction
POST /transactions
{
  "description": "Incorrect entry",
  "entries": [
    {"account_id": "cash", "entry_type": "debit", "amount": 100.00},
    {"account_id": "sales_revenue", "entry_type": "credit", "amount": 100.00}
  ]
}

// Reverse it
POST /transactions/{id}/reverse
{
  "reason": "Customer returned merchandise"
}

Monitoring & Analytics

Credit Usage Tracking

# Get usage events
GET /organizations/{org_id}/events?type=credits_consumed&limit=20

[
  {
    "event_type": "credits_consumed",
    "entity_type": "transaction",
    "entity_id": "txn_123",
    "credits_used": 2,
    "description": "Transaction created",
    "timestamp": "2024-01-15T10:30:00Z"
  }
]

Transaction Analytics

# Recent transactions
GET /organizations/{org_id}/transactions?limit=10&sort=-created_at

# Transactions by account
GET /organizations/{org_id}/accounts/{act_id}/transactions

# Search transactions
GET /organizations/{org_id}/transactions?search=invoice&amount[gte]=100

Next Steps

Continue Learning

1. Create more accounts - Build out your complete chart of accounts
2. Record various transactions - Sales, expenses, payments, adjustments
3. Set up customers/vendors - Create contact records
4. Generate invoices - Bill customers and track receivables
5. Bank reconciliation - Match transactions to bank statements

Advanced Topics

1. Multi-currency transactions - Handle international business
2. Recurring transactions - Automate regular entries
3. Transfer operations - Move money between accounts
4. Financial reports - Generate balance sheets and income statements
5. Audit trails - Complete transaction history and compliance

Congratulations on recording your first transaction! 🎉

You've now experienced:

• ✅ How double-entry bookkeeping works
• ✅ Credit consumption and cost awareness
• ✅ API transaction creation
• ✅ Account balance updates
• ✅ Transaction verification

Your accounting system is ready for business operations. Continue building your chart of accounts and recording transactions to maintain accurate financial records.

• ✨ For LLMs/AI assistants: Read our structured API reference