Multi-currency Support

Currency Management

Supporting Multiple Currencies for International Clients

Corcava provides comprehensive multi-currency support for international business operations:

Multi-Currency Architecture:

Team Base Currency: Each team has a configurable base currency for internal reporting
Client-Specific Currencies: Individual clients can have their own preferred currencies
Invoice Currency Selection: Invoices automatically use client currency or fall back to team base currency
Payment Currency Tracking: Payments tracked in both invoice currency and base currency
Comprehensive Currency Database: Support for major international currencies

Currency Management Features:

Currency Database: Complete database of international currencies with currency codes
Team Configuration: Team-level base currency configuration and management
Client Configuration: Client-specific currency preferences and settings
Automatic Selection: Automatic currency selection based on client configuration
Currency Relationships: Proper relationships between teams, clients, and currencies

International Business Support:

Global Client Management: Support for clients in different countries with local currencies
Currency Consistency: Consistent currency handling across all financial operations
Professional Invoicing: Invoices displayed in client's preferred currency
Financial Reporting: Multi-currency reporting with base currency conversion
Exchange Rate Integration: Real-time exchange rate integration for accurate conversions

Currency Configuration Options

Currency configuration provides flexibility for international operations:

Team Base Currency:

Base Currency Setting: Configurable base currency for each team (base_currency_id)
Default Currency: Team base currency used as default for new clients
Reporting Currency: Base currency used for internal financial reporting
Currency Change Support: Administrative commands for changing team base currency
Migration Support: Database migration support for currency configuration changes

Client Currency Settings:

Individual Client Currencies: Each client can have a specific preferred currency
Currency Override: Client currency overrides team base currency for invoicing
Automatic Detection: Currency selection based on client configuration
Fallback Logic: Fallback to team base currency when client currency not specified
Currency Validation: Validation of currency settings and relationships

Exchange Rate Handling

Automatic Currency Conversion and Exchange Rate Management

Exchange rates are managed through sophisticated real-time integration:

Exchange Rate Service:

Alpha Vantage Integration: Real-time exchange rates through Alpha Vantage API
Current Exchange Rates: Real-time current exchange rate retrieval
Historical Exchange Rates: Support for historical exchange rate data
Average Exchange Rates: Calculate average exchange rates over date ranges
Cached Exchange Rates: Cached exchange rates for performance optimization

Exchange Rate Features:

Real-Time Rates: Current exchange rates updated in real-time
API Integration: Professional API integration with Alpha Vantage service
Rate Caching: 2-hour caching of exchange rates for performance
Error Handling: Comprehensive error handling for API failures
Fallback Mechanisms: Graceful fallback when exchange rates unavailable

Exchange Rate Calculations:

Automatic Conversion: Automatic conversion between currencies during invoice creation
Coefficient Calculation: Exchange coefficient calculation and storage
Precision Handling: Proper decimal precision for financial calculations
Rounding Logic: Consistent rounding logic for currency conversions
Base Currency Conversion: Conversion to team base currency for reporting

Exchange Rate API Integration

Exchange rate integration provides reliable currency conversion:

Alpha Vantage API Integration:

CURRENCY_EXCHANGE_RATE: Real-time exchange rate endpoint
FX_DAILY: Daily historical exchange rate data
API Key Configuration: Secure API key configuration and management
Rate Limiting: Proper handling of API rate limits
Error Response Handling: Comprehensive error response handling

API Features:

Real-Time Data: Access to real-time currency exchange data
Historical Data: Access to historical exchange rate information
Reliable Service: Professional-grade API service integration
Comprehensive Coverage: Support for major international currencies
Data Validation: Validation of API responses and data quality

Caching and Performance:

Exchange Rate Caching: 2-hour caching of exchange rates (Cache::remember)
Performance Optimization: Optimized API calls and response handling
Cache Key Management: Proper cache key management for different currency pairs
Cache Invalidation: Automatic cache invalidation and refresh
Fallback Handling: Graceful handling when cached rates unavailable

Base Currency Configuration

Team Base Currency Settings and Conversions

Base currency configuration provides foundation for multi-currency operations:

Team Base Currency Management:

Base Currency Selection: Configurable base currency for each team
Currency Relationship: Direct relationship between teams and base currencies
Default Settings: Base currency used as default for new clients and invoices
Administrative Control: Administrative commands for changing team base currency
Migration Support: Database migration support for base currency changes

Base Currency Features:

Team Isolation: Base currency settings isolated by team
Currency Consistency: Consistent base currency usage across team operations
Reporting Foundation: Base currency serves as foundation for financial reporting
Conversion Reference: Base currency used as reference for all conversions
Administrative Management: Team administrators can manage base currency settings

Base Currency Applications:

Invoice Creation: Base currency used when client currency not specified
Financial Reporting: All financial reports use base currency for consistency
Payment Tracking: Payments converted to base currency for reporting
Exchange Rate Calculations: Base currency used as reference for exchange rates
Team Analytics: Team-level analytics use base currency for consistency

Currency Change Management

Currency changes are managed through administrative tools:

Team Currency Change Command:

Administrative Command: app:change-team-currency command for currency changes
Comprehensive Updates: Updates teams, clients, invoices, and related records
Data Integrity: Maintains data integrity during currency changes
Batch Processing: Efficient batch processing of currency updates
Audit Trail: Clear audit trail of currency change operations

Currency Change Process:

Team Update: Update team base currency setting
Client Updates: Update all team clients to new currency
Invoice Updates: Update existing invoices to new currency
Rate Updates: Update bill rates and project rates
Validation: Validate all currency changes for data integrity

Currency-Specific Invoicing

Creating Invoices in Client-Specific Currencies

Invoice creation automatically handles client-specific currencies:

Currency Selection Logic:

Client Currency Priority: Client-specific currency takes priority over team base currency
Automatic Detection: Automatic currency selection during invoice creation
Fallback Logic: Fallback to team base currency when client currency not set
Currency Validation: Validation of currency selection and compatibility
Professional Display: Professional currency display in invoices

Invoice Currency Features:

Currency Storage: Invoice currency stored with each invoice record
Exchange Coefficient: Exchange coefficient calculated and stored with invoice
Dual Amount Tracking: Amounts tracked in both invoice currency and base currency
Currency Display: Professional currency display in invoice templates
Payment Integration: Currency integration with payment processing

Currency Conversion Process:

Currency Detection: Detect client-specific currency or use team base currency
Exchange Rate Lookup: Lookup current exchange rate for currency conversion
Amount Conversion: Convert amounts between invoice currency and base currency
Coefficient Storage: Store exchange coefficient with invoice for consistency
Dual Tracking: Track amounts in both currencies for reporting

Multi-Currency Invoice Management

Multi-currency invoices are managed with comprehensive tracking:

Currency Tracking:

Invoice Currency: Primary currency for invoice display and client interaction
Base Currency Amounts: Converted amounts in team base currency for reporting
Exchange Coefficients: Exchange rate coefficients stored with each invoice
Currency Consistency: Consistent currency handling across invoice lifecycle
Professional Display: Professional currency formatting and display

Multi-Currency Features:

Dual Amount Storage: Amounts stored in both invoice currency and base currency
Exchange Rate Preservation: Exchange rates preserved for historical accuracy
Currency Validation: Validation of currency amounts and calculations
Professional Formatting: Professional currency formatting for different locales
Reporting Integration: Multi-currency integration with financial reporting

Multi-currency Reporting

Financial Reporting Across Different Currencies

Multi-currency reporting provides comprehensive financial insights:

Reporting Currency Management:

Base Currency Reporting: All reports use team base currency for consistency
Currency Conversion: Automatic conversion of multi-currency data to base currency
Exchange Rate Application: Historical exchange rates applied for accurate reporting
Consolidated Reporting: Consolidated financial reports across all currencies
Professional Presentation: Professional presentation of multi-currency data

Multi-Currency Analytics:

Revenue Tracking: Revenue tracking across multiple currencies with base currency conversion
Outstanding Balances: Outstanding balance tracking in base currency
Payment Analytics: Payment analytics with currency conversion
Client Analytics: Client-specific analytics with proper currency handling
Team Performance: Team performance metrics in consistent base currency

Reporting Features:

Currency Consistency: Consistent currency presentation across all reports
Historical Accuracy: Historical exchange rates preserved for accurate reporting
Professional Display: Professional currency formatting in reports
Consolidated Views: Consolidated views of multi-currency financial data
Export Capabilities: Export capabilities for multi-currency financial data

Currency Conversion Accuracy

Currency conversion maintains high accuracy standards:

Conversion Accuracy:

Real-Time Rates: Real-time exchange rates for accurate conversions
Decimal Precision: Proper decimal precision for financial calculations
Rounding Consistency: Consistent rounding logic across all conversions
Historical Preservation: Historical exchange rates preserved for accuracy
Validation Checks: Validation checks for conversion accuracy

Financial Integrity:

Audit Trail: Complete audit trail of all currency conversions
Data Consistency: Consistent currency data across all financial records
Error Prevention: Validation to prevent currency conversion errors
Professional Standards: Currency handling meets professional accounting standards
Regulatory Compliance: Currency handling supports regulatory compliance requirements