Formats a number as a specific numeric type, such as a decimal, currency, or percentage value. It can convert numbers stored in strings to a number data type and round numbers to a certain number of decimal places.
Availability
This helper is available in the Winter ’26 release of Marketing Cloud Next.
Syntax
{{formatNumber number formatType cultureCode}}
Parameters
| Parameter | Type | Description |
|---|---|---|
number |
Number or String | Required. The number to format. Must be convertible to a valid number. Assumes period (.) as decimal separator for string inputs. |
formatType |
String | Required. The number format type. See Format Types. |
cultureCode |
String | POSIX locale code for formatting, such as en_US or zh-TW. Supports both hyphen and underscore formats. The default is en_US. |
Format Types
This table lists the format types that you can use with the formatType parameter.
| Format Type | Description |
|---|---|
C |
Formats the number as a currency value. |
D |
Formats the number as a decimal number. |
E |
Formats the number using scientific notation. |
F |
Formats the number to a fixed number of decimal places. If you don't specify a number of decimal places, two decimal places are used. |
G |
Formats the number without thousands separators. |
N |
Formats the number with thousands separators. |
P |
Formats the number as a percentage. |
R |
Formats the number as a round-trip value. This format ensures that the value parsed from a string can be parsed back to a numeric value. |
X |
Formats the number as a hexadecimal value. |
Optionally, include a number after the format type to indicate the precision of the output. For example, C2 formats the number as a currency value with 2 decimal places, so {{formatNumber 1234.567 "C2"}} returns $1,234.57.
Return Value
The function returns a formatted string representation of the number using the specified format type and culture. When the input can’t be converted to a valid number, it returns an empty string (backward compatibility). Invalid format types and locale codes throw exceptions. Different cultures use different decimal separators, grouping patterns, and currency symbols.