The Currency Converter variable for the Google Tag Manager server container converts a monetary amount from one currency to another using exchange rates from one of three APIs: Frankfurter API (default), the Exchange API, or the paid Xe Currency Data API.
Use it to normalize purchase values into a single reporting currency before they reach Google Analytics 4, Google Ads, Meta, or any other destination — so every platform receives comparable revenue figures regardless of the currency the customer paid in.
Features
- Three APIs, one set of fields — choose Frankfurter, the Exchange API or Xe from a drop-down. Frankfurter and the Exchange API are free and need no account or API key. Xe needs a paid account and adds its own credentials and margin fields, which are only shown when Xe is selected. The rest of the configuration is the same for all three.
- Automap from Event Data — From Currency and Amount fall back to
eventData.currencyandeventData.value, so a single variable works across every ecommerce event without per-event configuration. - Built-in rate caching — rates are always requested for a single unit and cached in Template Storage, so one request serves every amount converted for that currency pair until the cache expires. Template Storage is kept per server instance, so each instance of your server container makes its own request.
- Optional margin (Xe only) — apply a percentage margin (+/-) on top of Xe’s mid-market rate, for example to model FX fees.
- Mirror fallback — when the Exchange API’s main CDN fails, the request falls back to its Cloudflare mirror.
- Flexible output — return the converted amount, the exchange rate on its own, or the rate data (
date,base,quoteandrate), which has the same shape for every API. - Configurable rounding — round the returned number to a fixed number of decimal places, or return it at full precision.
Choosing an API
| Frankfurter | Exchange API | Xe Currency Data | |
|---|---|---|---|
| Cost | Free | Free | Paid (7-day free trial) |
| Currencies | 165, from central banks and official sources | 200+, including cryptocurrencies | See the Xe documentation |
| Authentication | None | None | Account ID and API key |
| Quotas and rate limits | None | None | Depend on your Xe plan |
| Update frequency | Daily | Daily (the primary CDN can serve a rate up to about 12 hours old) | Live, 15-minute, hourly or daily, depending on your Xe plan |
| Margin | No | No | Yes |
Frankfurter and the Exchange API publish daily rates, so a long cache TTL is fine. Xe can refresh rates more often depending on your plan, so set the cache TTL accordingly. The APIs use different sources, so the same currency pair can return slightly different rates.
How to use the Currency Converter variable
- Add the Currency Converter variable to your server GTM container from the template gallery.
- Choose the API Provider. Frankfurter is the default.
- If you chose Xe, add your Account ID and API Key. They are sent as the username and password for HTTP Basic authentication, and you can find them in your Xe Currency Data account. You can request free API credentials for a 7-day trial on the Xe Currency Data API site.
- Set the To Currency — the code of your reporting currency, for example
EUR. - Optionally set the From Currency and the Amount. The Amount is only shown when What To Return is Converted Amount (step 6). With Automap from Event Data enabled (the default), leaving them empty falls back to
eventData.currencyandeventData.value; if neither is set, the variable converts1unit ofUSD. If an Amount is provided but is not a number, the variable returnsundefined. Disable the checkbox to require both values to be set explicitly. - Choose What To Return:
- Converted Amount (default) — the Amount multiplied by the exchange rate.
- Exchange Rate — the exchange rate for a single unit of the From Currency.
- Rate Data — an object with the
dateof the rate, thebaseandquotecurrencies and therate. Rates are always requested for a single unit, sorateis the exchange rate rather than the converted amount. Thedateis a day (YYYY-MM-DD) for Frankfurter and the Exchange API, and a full timestamp for Xe.
- Optionally set Decimal Places to round the returned number. Leave it empty to return the value at full precision.
- Under Advanced Settings, optionally add a Margin (%) (Xe only) and adjust the cache. Caching is enabled by default with a 60-minute TTL.
- Use the variable in your tags — for example as the
valueparameter of a GA4 or Conversion API tag.
The variable returns undefined when the To Currency is not set, when Xe is selected and its credentials are missing, when Converted Amount is selected and the Amount is not a number, or when the rate cannot be retrieved from the API (for example an API error, an unexpected response, or no rate for the requested currency).
Currency codes
Use ISO 4217 codes, for example USD. Codes are trimmed and converted to upper case. Frankfurter and the Exchange API support some precious metals (for example XAU), and the Exchange API also supports cryptocurrencies (for example BTC). For Xe, see its documentation for the supported codes. The supported codes are listed by Frankfurter and by the Exchange API.
Useful resources
- Frankfurter documentation
- Exchange API documentation
- Xe Currency Data API documentation
- ISO 4217 currency codes
Open Source
The Currency Converter Variable for GTM Server Side is developed and maintained by the Stape Team under the Apache 2.0 license.