# FORMAT\_CURRENCY

**The function FORMAT\_CURRENCY converts a currency into a string given an optional format string, and locale.**

This function takes a [Currency](../../variable-data-types/the-currency-variable-data-type) and converts it into a string given an optional format [string](../../variable-data-types/the-text-variable-data-type), and locale.

The format string specifies: whether to include thousandths separators, how many decimal places, and whether to include a symbol for the currency (such as a dollar sign: **$**). For example, the format string **"$0,0.00"** will include the currency symbol, group by thousandths, and display two decimal places, it would format one U.S. dollar as **"$1.00"**

The locale is used as in the [FORMAT\_NUMBER](../number-formatting-functions/format_number) function to determine which characters to use to group thousandths, and as the decimal point. In FORMAT\_CURRENCY, it is also used to determine which symbol to display to disambiguate currencies. For example, with a locale of **"en-US"**, and a currency of **"USD"**, the dollar sign will be chosen. However, in the **"en-CA"** locale, the symbol will be **"US$"** to disambiguate between Canadian dollars.

#### Declaration

```javascript
FORMAT_CURRENCY(currency, format_string, locale_string) -> formatted_string
```

#### Parameters

**currency** (required, type: _currency_) The currency to be formatted.

**format\_string** (optional, type: _string,_ default\*: **"$0,0.00"**\*) A string that configures how the currency is formatted.

**locale\_string** (optional, type: _string,_ default: **"en-US"**) The locale used to choose the currency symbol. Locale must match a valid [LCID String](https://www.science.co.il/language/Locale-codes.php).

#### Return Values

**formatted\_string** (type: _string_) A string containing the formatted **currency** as specified by the **format\_string**.

#### Examples

For the following examples assume that we have a variable named **us\_pennies** that holds a Currency that represents 101 U.S. pennies. Note that this is a different value from 1.01 dollars, as a Currency carries both an amount and a precision. See [Working with Numbers and Currency in Airscript](https://github.com/airkit/airkit-docs/blob/master/docs/v18-4/working-with-numbers-and-currency.md) for more details.

```javascript
us_pennies = CURRENCY(101, "USD", 2)
```

If we do not provide any of the optional arguments, the formatted currency will begin with a dollar sign (assuming a user locale of **"en-US"**), be grouped by thousandths, and have two decimal places.

```javascript
FORMAT_CURRENCY(us_pennies) -> "$1.01"
```

This is the same as if we had called FORMAT\_CURRENCY with the format string **"$0,0.00"**

```javascript
FORMAT_CURRENCY(us_pennies, "$0,0.00") -> "$1.01"
```

However, if we force the locale to be **"en-CA"** the currency symbol will instead be **"US$"**

```javascript
FORMAT_CURRENCY(us_pennies, "$0,0.00", "en-CA") -> "US$1.01"
```

Additional trailing zeros will increase the number of decimal places. For each zero after the period there will be an additional decimal place displayed in the final result.

```javascript
FORMAT_CURRENCY(us_pennies, "$0,0.0000") -> "$1.0100"
```

#### Discussion

The format string specification is as follows where terms surrounded by brackets, **\[** and **]**, are optional. Note that the format string must contain at least a zero, all other terms are optional.

```
[$] [0,] 0 [.precision]
```

1. If the first character is a dollar sign, the currency will be formatted with a leading currency symbol.
2. If there is a zero followed by a comma, the currency will be grouped by thousands.
3. There must be a zero
4. If there is a period followed by a number of zeros, the precision used will match the number of zeros provided. For example **.000** means that three decimal places should be displayed.
