FormatCurrency()

Formats a number as a currency value.

The FormatCurrency() function has four parameters:

  • number (string or number): Required. The number that you want to format. This function assumes that the input number uses a period or full stop (.) as a decimal separator. If you input the number as a string, the function assumes that commas are used as thousands separators.
  • cultureCode (string): Required. The locale code to use when formatting the number. Locale codes can use POSIX format (such as es_MX) or BCP 47 format (such as es-MX). When you provide this value, the resulting number is formatted using patterns that suit the specified locale.
  • decimalPlaces (number): The number of decimal places to include in the result. If you don't provide a value, the resulting number has two decimal places. If you’re specifying a value for the currencySymbol parameter, then this parameter is required.
  • currencySymbol (string): The currency symbol to use with the value. If you provide a value for this parameter, it overrides the default currency symbol for the specified locale.

To use the function, pass it a number to format, and culture code that you want to use to format it. This example converts a number to a currency value that is formatted based on the United Kingdom locale (en_GB).

%%=FormatCurrency(1234.555,"en_GB")=%%

The function returns £1,234.56.

The function can output a currency value that is rounded to a certain decimal place, or that adds precision to the currency value.

This example rounds the input number to the nearest whole number.

The example outputs CHF 1'235.

In some currencies, decimal divisions aren’t commonly used. For example, in Japan, the smallest unit of currency in current use is ¥1, and fractional divisions of the yen are uncommon. For this reason, the FormatCurrency() function rounds to the nearest yen by default. However, you can force the function to output a currency value by specifying a value for the third parameter, as in this example.

The example outputs ¥1,234.56.

You can force the function to output a currency value that uses a specific currency symbol. For example, many currencies use the dollar sign ($). You can use this feature to add information that helps the reader determine which currency you’re referring to. When you specify a currency symbol, you must also specify the number of decimal places to include in the output. This example replaces the default currency symbol for the Mexican peso ($) with an alternative (Mex$) that makes it easier to identify the currency being used.

The example outputs Mex$1,234.56.

This table shows the results of formatting a number (1234.555) as a currency value using several different locale settings.

LocaleFunctionOutput
China%%=FormatCurrency(1234.555,"zh_CN")=%%¥1,234.56
India%%=FormatCurrency(1234.555,"hi_IN")=%%₹1,234.56
United States%%=FormatCurrency(1234.555,"en_US")=%%$1,234.56
Indonesia%%=FormatCurrency(1234.555,"id_ID")=%%Rp1.235
Pakistan%%=FormatCurrency(1234.555,"ur_PK")=%%Rs 1,234.56
Nigeria%%=FormatCurrency(1234.555,"en_NG")=%%₦1,234.56
Brazil%%=FormatCurrency(1234.555,"pt_BR")=%%R$ 1.234,56
Japan%%=FormatCurrency(1234.555,"ja_JP")=%%¥1,235
Germany%%=FormatCurrency(1234.555,"de_DE")=%%1.234,56 €
France%%=FormatCurrency(1234.555,"fr_FR")=%%1 234,56 €
Canada (French-speaking areas)%%=FormatCurrency(1234.555,"fr_CA")=%%1 234,56 $
Canada (English-speaking areas)%%=FormatCurrency(1234.555,"en_CA")=%%$1,234.56
Türkiye%%=FormatCurrency(1234.555,"tr_TR")=%%₺1.234,56
Ukraine%%=FormatCurrency(1234.555,"uk_UA")=%%1 234,56 ₴
South Korea%%=FormatCurrency(1234.555,"ko_KR")=%%₩1,235
United Arab Emirates%%=FormatCurrency(1234.555,"ar_AE")=%%1,234.56 د.إ.‏
Philippines%%=FormatCurrency(1234.555,"fil_PH")=%%₱1,234.56
Sweden%%=FormatCurrency(1234.555,"sv_SE")=%%1 234,56 kr
Israel%%=FormatCurrency(1234.555,"he_IL")=%%₪ 1,234.56
Saudi Arabia%%=FormatCurrency(1234.555,"ar_SA")=%%1,234.56 ر.س.‏