Currency info hooks

  1. hook_commerce_currency_info()
  2. hook_commerce_currency_info_alter(&$currencies)


Commerce module endeavors to define all legal currencies, so please open an issue if yours is missing. However, modules can use this hook to add custom / site-specific currencies, such as user points or credits.

The currency data structure is as follows:

  • code - the three letter currency code as defined by ISO 4217
  • numeric_code - the three digit numeric code in string format with leading zeros
  • name - translatable full name of the currency in plural format
  • symbol - the symbol used to denote the currency if one exists
  • major_unit - the translatable name of the major currency unit in single format
  • minor_unit - the translatable name of the minor currency unit in single format
  • decimals - the number of decimals expressed when displaying the currency; defaults to 2
  • thousands_separator - the character used to denote thousands in the currency; defaults to ','
  • decimal_separator - the character used as a decimal marker in the currency; defaults to '.'
  • symbol_placement - 'before' or 'after' indicating where the symbol is placed in relation to the amount of a price when formatted for the currency; if not specified, the symbol will not be displayed
  • code_placement - like symbol_placement but used for displaying the currency code
  • format_callback - function used for formatting a price in this currency for display; if not specified, the formatting will happen within commerce_currency_format()
  • conversion_rate - conversion rate of this currency calculated against the base currency, expressed as a decimal value denoting the value of one majur unit of this currency when converted to the base currency; defaults to 1

Example currency definition:

<?php $currencies['USD'] = array( 'code' => 'USD', 'numeric_code' => '840', 'name' => t('United States Dollars'), 'symbol' => '$', 'major_unit' => t('Dollar'), 'minor_unit' => t('Cent'), 'symbol_placement' => 'before', ); ?>


Modules can use this hook to alter properties of any defined currencies. This hook should be used with extreme caution, as the currency code and decimals values of each currency are intimately tied into price field values. Changing codes and decimals values may cause wide disruption of store price values, so such alterations should be made prior to setting prices and collecting orders and not after moving to production.

Additionally, because every currency's default conversion rate is 1, this hook can be used to populate currency conversion rates with meaningful values. Conversion rates can be calculated using any currency as the base currency as long as the same base currency is used for every rate.

A single currency array is referred to as $currency. An array of currency arrays keyed by code is referred to as $currencies. The code of a currency is referred to as $currency_code.

Found errors? Think you can improve this documentation? edit this page