Multi-currency support

Manage multiple currencies and exchange rates in Firefly III

Firefly III provides comprehensive multi-currency support, allowing you to track finances across different currencies with automatic exchange rate management.

Overview

Firefly III supports:

• Multiple currencies for accounts and transactions
• Automatic currency conversion
• Custom exchange rates
• Foreign currency amounts on transactions
• Primary currency for reporting

Add currencies

Enable and configure additional currencies

Exchange rates

Manage currency exchange rates

Multi-currency transactions

Create transactions with foreign amounts

Primary currency

Set your reporting currency

Currency management

Enabling currencies

Firefly III comes with many currencies pre-configured. To enable a currency:

1. Navigate to currencies

   Go to Options > Currencies in the main menu

2. Enable currency

   Find the currency you want to use and click Enable

3. Set as default (optional)

   You can optionally set this as your default currency for new accounts

Each user group can have its own set of enabled currencies and exchange rates

Primary currency

Your primary currency is used for:

• Financial reports and charts
• Budget calculations
• Net worth calculations
• Dashboard summaries

To change your primary currency:

1. Go to Profile > Preferences
2. Find the Primary currency setting
3. Select your preferred currency
4. Save changes

Changing your primary currency will trigger a recalculation of all transaction amounts. This may take some time for large datasets.

Exchange rates

Firefly III uses exchange rates to convert between currencies. Exchange rates are stored per date, allowing historical accuracy.

Exchange rate model

Exchange rates in Firefly III consist of:

• From currency: Source currency code (e.g., EUR)
• To currency: Target currency code (e.g., USD)
• Date: The date this rate applies to
• Rate: The conversion rate (stored as string for precision)

Managing exchange rates

Manual entry

1. Navigate to exchange rates

   Go to Options > Currencies > Exchange rates

2. Add new rate

   Click Add exchange rate and fill in:

   • From currency
   • To currency
   • Date
   • Exchange rate
3. Save

   Click Submit to save the exchange rate

API

Use the Exchange Rates API endpoints:

# Get exchange rate
curl -X GET "https://your-firefly.local/api/v1/exchange-rates/EUR/USD" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get rate for specific date
curl -X GET "https://your-firefly.local/api/v1/exchange-rates/EUR/USD/2024-01-01" \
  -H "Authorization: Bearer YOUR_TOKEN"

Automatic rate fetching

Firefly III can automatically fetch exchange rates from external sources if configured. Check your .env file for CURRENCY_EXCHANGE_PROVIDER settings.

Multi-currency transactions

You can create transactions that involve multiple currencies, useful for:

• International transfers
• Foreign purchases on credit cards
• Travel expenses
• International business transactions

Creating multi-currency transactions

1. Create transaction

   Start creating a new transaction as usual

2. Select accounts

   Choose your source and destination accounts

3. Enter foreign amount

   If the accounts use different currencies:

   • Enter the amount in the source account’s currency
   • Optionally enter the foreign currency amount
   • Firefly III will calculate the exchange rate or use the existing rate
4. Review exchange rate

   The calculated exchange rate will be shown. You can override it if needed

Foreign currency amounts

For transactions in your account’s currency but with foreign amounts:

# Example: EUR account, USD purchase
Account currency: EUR
Transaction amount: 10.00 EUR
Foreign amount: 11.50 USD
Foreign currency: USD

This is useful for:

• Credit card transactions in foreign currencies
• Online purchases with currency conversion
• Tracking the original purchase amount

Always enter the foreign amount when available. This provides more accurate tracking and reporting.

Currency conversion in reports

When viewing reports and charts, Firefly III automatically converts all amounts to your primary currency using:

1. Historical rates: Uses the exchange rate valid on the transaction date
2. Fallback rates: If no rate exists for that date, uses the nearest available rate
3. Default rate: If no rates are configured, defaults to 1:1 (not recommended)

Primary currency amounts

Each transaction stores:

• Original amount: In the account’s native currency
• Primary currency amount: Converted amount in your primary currency
• Exchange rate used: For audit purposes

Primary currency amounts are recalculated when you change your primary currency or update exchange rates

Best practices

Keep exchange rates updated

Regularly update exchange rates, especially for frequently used currency pairs. Outdated rates can lead to inaccurate reporting.

Use foreign amounts consistently

When making foreign currency transactions, always enter both the converted and original foreign amount for better tracking.

Set appropriate primary currency

Choose your primary currency based on where you live and earn income, not based on your strongest currency holdings.

Consider account currency carefully

When creating accounts, set the currency to match the actual account’s currency at the financial institution.

Regular reconciliation

Reconcile multi-currency accounts regularly to catch any exchange rate discrepancies early.

Troubleshooting

Incorrect conversion rates

Problem: Amounts are being converted at wrong rates

Solutions:

• Check that exchange rates are entered correctly
• Verify the date on your exchange rates
• Ensure you’re using the correct currency codes (EUR, USD, not Euro, Dollar)
• Clear cache: php artisan cache:clear

Missing exchange rates

Problem: Error about missing exchange rates

Solutions:

• Add the required exchange rate for the transaction date
• Enable automatic exchange rate fetching if available
• Verify both currencies are enabled

Primary currency changes not reflecting

Problem: Changed primary currency but amounts still show in old currency

Solutions:

• Wait for background recalculation to complete
• Check logs for any errors during recalculation
• Manually trigger recalculation: php artisan firefly-iii:upgrade-primary-currency-amounts

API reference

For programmatic currency management, see:

• Currencies API - Manage currencies
• Exchange Rates API - Get and set exchange rates
• Transactions API - Multi-currency transactions

Related features

Accounts

Set currency for each account

Transactions

Create multi-currency transactions

Reports

View consolidated reports in primary currency

Budgets

Budget in your primary currency