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.

Availability

This helper is available in the Winter ’26 release of Marketing Cloud Next (API version 65.0).

Syntax

1{{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.