---
schema_version: "1"
id: 7313758fcb33e58d39098b4eb63f5d9b75c85adbb3e6921cb6283f7bc513fcfb
title: "Handlebars Helper Function: formatNumber"
collection: developer
version: current
locale: en-us
portal_url: https://docs.salesforce.com/developer/current/en-us/marketing-cloud/handlebars/reference/utility/mcn-handlebars-reference-utility-formatnumber.md
canonical_url: https://developer.salesforce.com/docs/marketing/handlebars-for-marketing-cloud-next/references/mcn-handlebars-utility-references/mcn-handlebars-reference-utility-formatnumber.html
source_site: developer.salesforce.com
content_type: documentation
content_hash: 36f929306c5d60388e5a75406e429f7ba63e2ee17a5b010099909207a196ca46
products:
  - Handlebars for Marketing Cloud Next
  - Marketing Cloud
---
# Handlebars 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.

## Syntax

```handlebars
{{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](#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.

## See Also

- [formatCurrency](https://developer.salesforce.com/docs/marketing/handlebars-for-marketing-cloud-next/references/mcn-handlebars-utility-references/mcn-handlebars-reference-utility-formatcurrency.md)
- [format](https://developer.salesforce.com/docs/marketing/handlebars-for-marketing-cloud-next/references/mcn-handlebars-utility-references/mcn-handlebars-reference-utility-format.md)