Skip to content


Currency functionality is provided by the commerceguys/intl library. It relies on the CLDR dataset for locale-specific patterns for formatting and displaying numbers and currency values. See Commerce 2.x Stories - Internationalization for a detailed introduction and backstory for the commerceguys/intl library.


Commerce without borders means we support every language and every denomination of currency. This is a big undertaking because not only do we need to support various currencies, we need to support their regional formatting rules, what each currency is called in every other language, and many other difficult problems.

Commerce 2’s currency support is built upon the commerceguys/intl library which provides a list of currencies, currency formatting, countries, and languages. This list in not something we cooked up on the back of a napkin, the intl library uses the internationally-recognized standard of CLDR data. We parse the CLDR definitions into our own more compact YAML definitions and use them to re-implement intl’s NumberFormatter and provide currency, country, language data.

Currency Landing Page

Currency entity

The Drupal Commerce Price module provides a configuration entity for storing currency definitions. A Currency entity has the following properties:

Property Description Example
currencyCode A unique alphanumeric currency code, consisting of three uppercase letters, as defined by the ISO 4217 standard. GBP
name The currency name, a string. British Pound
numericCode A unique 3-digit numeric currency code, a string. 826
symbol The currency symbol, a string. £
fractionDigits The number of fractions digits, an integer between zero and six. 2

Importing currencies

While it is possible to create a custom currency, typically you will want to import the definition for an existing currency into your site using the CurrencyImporter service. This is the service that is used when an adminstrative user adds a currency to the site:

Add currency UI

For instructions on managing currencies, see the Adding a currency page in the Drupal Commerce User guide.

When the price module is installed, the currency importer service is used to import a default currency based on the site's default country (or US if not set). When new languages are installed, the currency importer service is used to import currency translations.

The CommerceGuys\Intl\Currency\CurrencyRepository class provides the data values used to set the Currency code, name, numeric code, symbol and fraction digits properties for the Currency entity that's created. For more information about the Currency Repository, see the Formatting Prices documentation.