Setting up currencies and exchange rates in the 1C-Bitrix online store

Currency and Exchange Rate Configuration in 1C-Bitrix E-Commerce

The currency module in 1C-Bitrix handles currency storage, exchange rates, and formatting rules. Without proper currency setup, catalog, cart, and reports cannot function — the system won't be able to bring prices to a common denominator. Let's examine the currency subsystem architecture, automatic rate updates, and multi-currency catalog specifics.

Currency Storage Structure

All currencies are registered in b_catalog_currency table. Each record contains three-character ISO code (RUB, USD, EUR), sort order, and creation date. Formatting parameters — separators, decimal places, output template — are stored separately in b_catalog_currency_lang bound to site language. This allows showing "$100.00" to English speakers and "100,00 USD" to Russian speakers.

Exchange rates are fixed in b_catalog_currency_rate. Each rate is bound to currency pair "currency → base currency" and date. Bitrix uses the nearest date rate for conversion, so records must be updated regularly.

Base currency is set in currency module settings. All internal calculations — discounts, markups, reports — are done in it. Changing base currency on a working store without recalculating prices is a direct path to order chaos.

Automatic Exchange Rate Updates

Manual rate updates are acceptable for stores with fixed prices in one currency. In all other cases, an agent is needed.

Bitrix out of the box can fetch rates from Russian Central Bank (cbr.ru) and European Central Bank (ECB). Configuration is done in Currencies → Rate Updates section. Agent \Bitrix\Currency\CurrencyManager::updateCurrencyRates runs on schedule via agent system.

Agent mechanics:

1. Agent requests selected provider (Russian CB or ECB) via HTTP.
2. Parses XML response, extracting rates of needed currencies.
3. Writes new values to b_catalog_currency_rate with current date.
4. If request fails — rate is not updated, previous value remains.

Typical problems:

• Agent doesn't run — check cron for cron_events.php and b_agent table. Without cron agents execute only on hits, and on low-traffic sites rates may not update for days.
• Timezone discrepancy — Russian CB publishes rates next day around 15:00 MSK. Agent run at 8:00 will get "yesterday's" rate.
• Need non-standard provider (e.g., Belarus National Bank or Forex API) — must write custom handler implementing \Bitrix\Currency\RateProvider interface. getRate() method should return array of rates in format compatible with standard save.

For production systems, it's recommended to duplicate rate updates with separate cron script that logs and sends alert on provider unavailability.

Multi-Currency Catalog

Multi-currency in Bitrix works on two levels: price storage and display.

At storage level, each price type (b_catalog_price) is bound to specific currency. Can set wholesale price in EUR and retail in RUB. Bitrix converts all prices to base currency when comparing and sorting in catalog.

At display level, catalog.element and catalog.section components use CCurrencyLang::CurrencyFormat() method for formatting. Display currency is determined by:

• Explicitly — via component parameter CURRENCY_ID.
• Automatically — by site setting or user geolocation.

Cart conversion happens at product addition moment. \Bitrix\Sale\Basket object stores price in order site currency. If product has USD price and site works in RUB — conversion is done at current rate. After adding to cart, price is fixed and not recalculated on rate change (unless explicitly recalculating).

For showing prices in user currency without actual conversion, JavaScript recalculation on client side is used. Server price remains in base currency, on frontend is multiplied by rate passed via BX.Currency.setCurrencyFormat(). This approach reduces server load but requires careful synchronization of rates between server and client.

Configuration Recommendations

• One base currency — don't change it after store launch.
• Cron is mandatory — don't rely on agents by hits for rate updates.
• Rounding — set rounding rules in currency settings, otherwise you'll get penny discrepancies between catalog and cart.
• Rate cache — currency module caches rates. After manual update, clear cache via \Bitrix\Currency\CurrencyManager::clearCurrencyCache().