Explicit currency formatting​

Multiple currencies can use the same currency symbol (such as $) which can make it difficult for customers to know the exact currency applied to their shopping.

To avoid this confusion, you can use explicit currency formatting to display the currency code alongside the price.

In this tutorial, you'll learn how to create a setting that lets merchants enable explicit currency formatting, and then apply it to price displays. You can also review guidelines for price displays and currency formatting.

Resources​

To add explicit currency formatting to your theme, you'll use the following Handlebars filters:

• The money_with_currency helper
• The money helper

Implement explicit currency formatting​

To enable explicit currency formatting, you need to implement the following components:

• A currency code theme setting: This setting enables merchants to choose whether the currency code is included in price displays.
• References to the theme setting in price displays: Reference the currency code theme setting to display the appropriate currency format in price displays.

Create a currency code theme setting​

You can create a section theme setting to enable merchants to choose whether the currency code is included in price displays.

In the example below, a Show currency codes checkbox setting with the ID currency_code_enable is exposed to the merchant.

...
{
  "name": "Currency format",
  "settings": [
    ...
    {
      "type": "checkbox",
      "id": "currency_code_enable",
      "label": "Show currency codes",
      "default": true
    }
    ...
  ]
}

Reference the theme setting in price displays​

After you create the theme setting, you can update theme price displays to show the currency code, or not, depending on the setting.

You shouldn't update all price displays to reference the currency code setting. To learn where you should and shouldn't use this setting in a theme, refer to Guidelines for updating price displays.

Your code should do the following:

1. Check the value of the currency setting to determine whether currency codes are enabled.
2. If currency codes are enabled, show the price with currency code by applying the money_with_currency helper to the price display.
3. If currency codes aren't enabled, show the price without the currency code by applying the money helper to the price display.

{{#if settings.currency_code_enable}}
    {{ money_with_currency product.price }}
{{else}}
    {{ money product.price }}
{{/if}}

Guidelines for updating price displays​

Most price displays should be updated to reference a currency code theme setting. However, there are some areas that should be hardcoded to provide the best customer experience or avoid repetition.

Displays that should always use explicit currency formatting​

Cart and checkout totals should always use explicit currency formatting so that there's no confusion for customers when they place an order.

Displays that shouldn't use explicit currency formatting​

The following price displays have enough surrounding context for customers to safely infer the currency. The shorter format also fits better within the display.

Price display	Example
Itemized prices in a cart or order
Unit prices