Formatting amounts in the right currency
Amounts in your templates should show the currency of the claim they are about, written the way the reader expects for the template's language. There are two ways to get this:
- Localized placeholders for the claim's and the account's own amounts, such as the balance or the fees.
- The
formatCurrencyhelper for any other amount you write into the template yourself, such as a fixed late fee.
Both work in emails, SMS and letters, and on landing pages. Both use the same currency and the same formatting, so a template that mixes them looks consistent.
Localized placeholders
These placeholders are already formatted as money, in the claim's currency and the template's language:
| Placeholder | Shows |
|---|---|
{{localizedAmount}} | The claim amount, without fees |
{{localizedTotalFees}} | The claim's fees |
{{localizedTotalAmount}} | The claim amount including fees |
{{account.localizedAmount}} | The account amount |
{{account.localizedTotalFees}} | The account's fees |
{{account.localizedTotalAmount}} | The account total |
{{account.localizedExpensesAmount}} | The account's expenses |
{{account.localizedIncomesAmount}} | The account's incomes |
The placeholders without localized, such as {{totalAmount}}, are the same amounts as plain numbers in cents (10200 for 102.00). Every amount in templates is in cents, including the ones you pass to formatCurrency below. Use the plain placeholders where a number is expected, for example in a payment QR code or a calculation.
Dates have localized placeholders too, such as {{localizedDueDate}} and {{localizedCurrentDate}}.
Fixed amounts: formatCurrency
When a template states an amount that is not a claim field, write it with formatCurrency instead of typing the symbol yourself:
The same template then reads correctly for every claim it is sent for:
| Template language | Claim in EUR | Claim in GBP |
|---|---|---|
| German (de-DE) | 40,00 € | 40,00 £ |
| English (en-GB) | €40.00 | £40.00 |
This replaces a condition per amount, such as:
Writing the amount
Write the amount in cents, like every other amount in templates: 4000 for 40.00, 1250 for 12.50. The amount must be a whole number; 12.5 or 40,00 stops the message, so a mistake does not go out with the wrong amount.
Because the units match, you can also pass an amount placeholder or a meta field that holds an amount in cents. {{formatCurrency totalFees}} shows the same text as {{localizedTotalFees}}, and {{formatCurrency meta.lateFee}} works the same way.
Which currency and language it uses
- Currency: the claim's currency. For a message about an account rather than a single claim, the account's currency, or if the account has none, the currency of its first claim.
- Language: the language of the template being sent.
formatCurrency keeps using them inside {{#each}} and {{#with}} blocks.
To show an amount in a specific currency or format regardless of the claim, add the currency code and, optionally, the language:
The currency is a three-letter ISO code such as EUR, GBP or USD. The language is a code such as de-DE or en-GB.
On landing pages
Landing pages show amounts with the currency code rather than the symbol, the same as their localized placeholders: 40,00 EUR in German and EUR 40.00 in English.
When the currency is missing or invalid
If no currency can be found for the message, or the currency code you wrote is not a valid ISO code, the message is not generated, the same as for a placeholder that cannot be filled in. The failure names the formatCurrency expression, so you can see what to fix. This is deliberate: an amount without a currency, or in the wrong one, is worse than a message that is held back.
The same applies to an amount that is not a whole number of cents, such as 12.5 or a meta field that holds text.
In the AI editor, ask "add a late fee of 40 in the claim's currency" and the assistant writes it with formatCurrency for you.