Currencies

Zen Cart comes preconfigured with several currencies, including the US dollar, the Euro, the Pound, the Canadian Dollar, and the Australian Dollar.

You may add a new currency, or edit the existing ones.

Currencies in Zen Cart

Adding Currencies

To add a new currency, click on the new currency button. You will then enter the information about this new currency in the input area. After you finish entering the new information, click on the Insert button to save this new currency entry.

Title

This is the name of the new currency, like Canadian Dollar or Mexican Peso.

Code

This is the three-character ISO 4217 international name for the currency you just described, like CAD for Canadian Dollar, MXN for Mexican Peso, USD for US Dollar, or JPY for Japanese Yen, etc. Note that to use the automated currency conversion feature (see the explanation for the update currencies button below), this code must be the correct one for that currency. If you don’t know the international code for the currency you want to add, you can find it in several places:

  • In ISO standard 4217
  • On Wikipedia, at the entry for ISO 4217
  • On XE.COM, which in addition to the ISO 4217 have the list of symbols used for most currencies, ($ for Dollar, ₭ for Euro, £ for Pound, ¥ for Yen, etc.), as well as currency conversion between almost all world currencies (you’ll need that for the Value field below if you want to manually process currency conversions as opposed to using the automated currency converter (see the explanation for the update currencies button below), don’t know what the usual currency conversion rate is between your currency and that one).

Symbol Left

If, when this currency is displayed, some symbol usually appears before (to the left of) the amount when it is displayed, enter that here. If no symbol commonly appears before the amount (like CA$ for Canadian Dollar) leave this field blank. This is separate from, and in addition to Symbol Right below.

Symbol Right

If, when this currency is displayed, some symbol usually appears after (to the right of) the amount when it is displayed, enter that here. If no symbol commonly appears before the amount (like CAN for Canadian Dollar) leave this field blank. This is separate from, and in addition to Symbol Left above.

Decimal Point

This is where you indicate what symbol appears between whole and fractional amounts of this currency. For U.S. and Canadian dollars, this is a period; in some countries it is a comma.

Thousands Point

This is where you indicate what symbol appears between thousands of whole amounts of this currency. For U.S. and Canadian dollars, this is a comma; in some countries it is a period.

Decimal Places

This indicates the number of decimal places appear to the right for this currency. U.S. and Canadian dollars have two digits after the decimal point. Some currencies may have four or six.

Value

This is the value of the other currency relative to the default currency for your store. Your default currency should have a value of exactly 1.

If you are going to use the automatic conversion feature (see the Update Currencies button below), then you can simply leave this field blank (or enter zero, both are the same) and let the website update the value.

If you do not wish to use the automatic conversion feature, here are some examples for conversions. Note that these are sample values, you will want to know what the usual conversion rate is at the current time as currency rates can fluctuate.

If Your default Currency is And you wanted to create a new currency of And the price of that currency in your default currency is You would use this for the amount in the _value_ field.
US Dollar Euro 1.27 0.7835
US Dollar British Pound 1.86 0.5367
US Dollar Canadian Dollar 0.8840 1.1312
US Dollar Mexican Peso 0.0921 10.858
Euro US Dollar 0.7836 1.2726
British Pound Euro 0.6849 1.46
British Pound Vietnam Dong 0.0000335444 29,811.25
Canadian Dollar Euro 1.4435 0.6927
Canadian Dollar Mexican Peso 0.1042 9.59908
Mexican Peso Euro 13.8570 0.0721657
Japanese Yen US Dollar 0.0087 114.655

Set as Default

If this is the default currency for this store, you will want to check this box. Note it may require some manual changes, as is indicated in the box, thus you might want to set this before loading any pricing data.

After you finish, click on the Insert button to save this new currency entry. If you decide you do not want this entry, click on cancel and the new entry will not be added.

Update Currencies

If you have the correct ISO 4217 code in the code column, you can click on the update currencies button to have the site request current exchange rate values from various conversion sites on the Internet for all currencies that have a correct ISO 4217 code, and the website will obtain current values and automatically correct the exchange rates.

Rates that are correctly converted will be listed in green at the top of the page. Rates that were not correctly converted will be listed in red. The website will probably try more than one converter if it has a failure in converting a particular currency. Pay attention to any red items in case you may have misspelled the ISO 4217 code for that currency, as it will not have been correctly updated. Any that were not correctly updated (either because of error or because the conversion site did not have the correct values for that currency) will have to be manually updated using the edit feature.

Once you have verified that clicking the Update Currencies button operates correctly and without errors, you can optionally create a cron job in your hosting company’s control panel to run the update automatically on a scheduled basis. The command to give it is as follows. Work with your hosting company’s tech support team if you need help with determining the correct path and the correct php binary to call.

php /full/server/path/to/admin/currency_cron.php

Editing an existing currency

If you only need to correct the exchange rate, you can use the update currency button to change all conversions on your website. If, however the automatic conversion does not work for one or more currencies or you need to change something else (for example, you entered Russian Rubles using code RUS instead of RUB), you would need to change that. Click on the line showing the currency you want to change. The right arrow will appear in the action column, then click on the edit button.

A series of entry fields, same as provided for the add new currency button will appear, only the values of those fields will be loaded with the current values. Change any fields as appropriate, then once you are finished, click on the update button to save these changes. If you decide you do not want these changes, click on cancel to leave the original values intact.

Deleting an existing currency

If you no longer want a particular currency, click on the line showing the currency you want to delete. The right arrow will appear in the action column, then click on the delete button. You will be asked to confirm if you want to delete that currency. Click on the delete button again to do so, or click the cancel button if you do not wish to delete this particular currency.

If you are deleting all currencies except your “default” currency, be sure to set that Default currency’s exchange rate Value to 1.0000.

Not displaying the Currencies box

If you only operate with one currency, Euro for example, you may wish to delete all others and set the exchange value to 1.

With just one currency in use, you will most likely want to stop the currency selection box from being displayed.

To do this:

  1. From the Tools menu, click “Layout Boxes Controller”.
  2. find ‘sideboxes/currencies.php’ in the list. It may be near the bottom. Click it.
  3. set both “Left/Right Column Status” and “Single Column Status” to off.
  4. Click Update.



Still have questions? Use the Search box in the upper right, or try the full list of FAQs. If you can't find it there, head over to the Zen Cart support forum and ask there in the appropriate subforum. In your post, please include your Zen Cart and PHP versions, and a link to your site.

Is there an error or omission on this page? Please post to General Questions on the support forum. Or, if you'd like to open a pull request, just review the guidelines and get started. You can even PR right here.
Last modified December 14, 2020 by Chris Brown (d7139edc).