> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omneo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Transaction conversion

> How the Currencies extension records an exchange rate and converted total on each Transaction made in a currency other than your base currency.

Transaction conversion gives every foreign currency Transaction a value in your base currency, at the rate for the day it happened.

## When it runs

The extension acts on the `transaction.received` and `transaction.resent` events. It converts a Transaction when:

* the extension is enabled for your tenant, and
* the Transaction has a `currency`, and
* that `currency` is not your `base_currency`.

A Transaction already in your base currency, or with no currency, is left unchanged and gets no `currency_values` entry.

## Which rate is used

The rate is the market rate from the Transaction's currency to your base currency on the Transaction's date, which is the UTC calendar day of `transacted_at`. A Transaction with no `transacted_at` uses today's rate.

A `transacted_at` in the future always means the timestamp reached Omneo wrong. The extension then uses the latest available rate instead of failing. Fix the timestamp at its source, because the stand-in rate is only an approximation.

Once a rate has been looked up for a currency and day, it is kept and reused for every later Transaction on that day, so all Transactions for that currency and day convert at the same rate.

## What is recorded

The extension updates the Transaction with the pair and rate. Omneo stores them as one entry in the Transaction's `currency_values`:

| Field | Value |
| - | - |
| `from` | The Transaction's currency. |
| `to` | Your base currency. |
| `rate` | The exchange rate, stored to six decimal places. |
| `total` | The Transaction's `total` multiplied by `rate`, rounded to two decimal places. |

If your tenant does not hold the currency pair yet, Omneo creates it with this rate. Resending the Transaction (`transaction.resent`) replaces the entry rather than adding a second one. The entry appears in the Transaction [event context](/dev-guides/webhooks/event-contexts) and the Transaction API.

## Waiting for conversion before loyalty

A Transaction created with `need_action` set to `true` fires `transaction.received` instead of `transaction.created`. That gives the extension time to record the rate before any loyalty Reaction runs. The update fires `transaction.updated`, and a Reaction on that event releases the Transaction:

```json theme={null}
{
  "and": [
    { "==": [{ "var": "need_action" }, true] },
    { "non_empty_array": { "var": "currency_values" } }
  ]
}
```

When the filter passes, a `transaction.update` action sets `need_action` to `0` and fires `transaction.created`. Your loyalty Reactions then run on `transaction.created` as normal, and can read the converted `total` from `currency_values`.

<Warning>
  Transactions in your base currency get no `currency_values` entry, so this filter never releases them. Give them their own Reaction, for example one on `transaction.received` that releases any Transaction whose `currency` is your base currency.
</Warning>

## When a Transaction is not converted

A Transaction held at `need_action: true` with an empty `currency_values` was not converted. Common causes are a currency the rate service does not price, a temporary rate service failure, or a very large Transaction payload. Ask your Omneo contact to check the cause, then resend the Transaction to convert it.

## Related

* [Currencies overview](/extensions/currencies/overview)
* [Setting up the Currencies extension](/extensions/currencies/setup)
* [Transactions](/concepts/commerce/transactions)
* [Filters](/dev-guides/reactions/filters)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.