Why Does Connectorly Calculate Unrealised Currency Gains?
Unrealised currency gains cannot be retrieved through the Xero API, as detailed in this Xero support article. As a result, Connectorly employs its own approach to calculate these and sources FX rates independently.
Connectorly Unrealised Currency Gains Journal entries normally has Account Code 498 with Journal Type of FX EXPOSURE.
Why Does Connectorly Calculate Realised Currency Gains?
Xero does return Realised Currency Gains through the API. These calculations use Xero's method which is not documented and as far as we can tell, doesn't appear to be applied consistently (or certainly not as we would expect).
Xero does not seem to include all foreign exchange transactions, leading to unpredictable outcomes. As an example, foreign exchange invoices that are issued and paid at exactly the same time (for example an invoice generated immediately after a Stripe foreign exchange payment has been made by a customer) sometimes have FX gains/losses calculated for them and sometimes don't.
The logic behind Xero’s method is not publicly documented, and this leads to confusion and uncertainty as to what is actually being calculated.
Therefore, Connectorly calculates Realised Currency FX movements and these are consistent with the Unrealised FX movements we calculate.
You may need to filter out Xero or Connectorly Realised Currency Gains from your reports
Because data contains both Connectorly and Xero Realised Currency Gains, you will need to filter one set out in your reports to avoid double counting.
Xero Realised Currency Gains Journal entries normally has Account Code 499 with Journal Type of ACTUAL.
Connectorly Realised Currency Gains Journal entries normally has Account Code 499 with Journal Type of FX EXPOSURE.
Differences in FX Rates
Connectorly retrieves foreign exchange (FX) rates from OpenExchangeRates.org, accurate to six decimal places. Xero, on the other hand, sources FX rates from XE.com, and typically provides rates with fewer decimal places (often two decimal places), resulting in slight but meaningful differences.
Connectorly's Calculation Methodology
Connectorly employs a clear, consistent, and fully auditable method to calculate Unrealised and Realised currency movements as follows:
Unrealised Currency Movements
Daily, unrealised FX movement Journals are created for every unpaid foreign currency invoice or bill against the closing rate for the day. These clearly cite the FX rates involved, the source, and overall movement.
With the exception of the first day, movements are calculated as the difference between the previous days closing FX rate to the current days closing FX rate using OpenExchangeRates.org data.
In the case of the first day, we use the opening FX rate against the invoice as provided by Xero and that days closing FX rate as per OpenExchangeRates.org data.
Connectorly Unrealised Journal properties
Journals for Unrealised Currency movements have the following properties:
Account Code | 498 unless this has been changed in your chart of accounts |
Account Name | Unrealised Currency Gains unless this has been changed in your chart of accounts |
Contact ID | The Contact ID from the source Invoice |
Contact Name | The Contact Name from the source Invoice |
Description | e.g. <Contact Name>, Invoice Number <Invoice Number> for 149.00 AUD valued close of day at 74.85 GBP with AUD:GBP 1.990603 (latest rate on 2025-02-01, up to and including 23:59:59 UTC, source https://openexchangerates.org) |
Gross Amount | The effect of that days FX movement on the Gross Amount |
Journal Date | The date the movement applies to |
Journal Number | These will start at 900,000,000 |
Journal Type | FX EXPOSURE |
Net Amount | The effect of that days FX movement on the Net Amount |
Source ID | The Invoice ID of the Invoice this has been calculated for |
Source Table | Invoices |
Tax Amount | The effect of that days FX movement on the Net Amount |
Realised Currency Movements
When the Invoice or Bill is paid, we create a Journal to reverse out the unrealised FX movements and create a realised FX movement Journal.
Connectorly Realised Journal properties
Journals for Realised Currency movements have the following properties:
Account Code | 499 unless this has been changed in your chart of accounts |
Account Name | Realised Currency Gains unless this has been changed in your chart of accounts |
Contact ID | The Contact ID from the source Invoice |
Contact Name | The Contact Name from the source Invoice |
Description | e.g. <Contact Name>, Invoice Number <Invoice Number> for 149.0 AUD realised fx gain/loss calculated with AUD:GBP opening rate of 1.995160 on 2025-02-01 (source Xero) and closing rate of 1.990603 on 2025-02-01, up to and including 23:59:59 UTC, source https://openexchangerates.org) |
Gross Amount | The effect of the FX movement on the Gross Amount during the period the Invoice or Bill was unpaid. |
Journal Date | The date the movement applies to |
Journal Number | These will start at 900,000,000 |
Journal Type | FX EXPOSURE |
Net Amount | The effect of the FX movement on the Net Amount during the period the Invoice or Bill was unpaid. |
Source ID | The Invoice ID of the Invoice this has been calculated for |
Source Table | Invoices |
Tax Amount | The effect of the FX movement on the Tax Amount during the period the Invoice or Bill was unpaid. |
Important Consideration
Remember, realised and unrealised currency gains/losses are indicative figures reflecting currency movements—they are not actual cash transactions. Actual gains or losses only materialise when currency exchange transactions occur (for example, exchanging USD into GBP).
If you have further questions or need clarification, please contact our support team—we're happy to help!