Handlebar Helper Function: FormatNumber
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.
This helper is available in the Winter ’26 release of Marketing Cloud Next (API version 65.0).
| 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. |
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.
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.