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:

1. Team Update: Update team base currency setting 2. Client Updates: Update all team clients to new currency 3. Invoice Updates: Update existing invoices to new currency 4. Rate Updates: Update bill rates and project rates 5. 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:

1. Currency Detection: Detect client-specific currency or use team base currency 2. Exchange Rate Lookup: Lookup current exchange rate for currency conversion 3. Amount Conversion: Convert amounts between invoice currency and base currency 4. Coefficient Storage: Store exchange coefficient with invoice for consistency 5. 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