Difference between revisions of "Currencies"

Latest revision as of 16:22, 7 July 2022

WHMCS supports all global currencies as well as syncing of product prices across currencies. Currency support applies to all currency values throughout WHMCS (for example, product and addon pricing). You can change WHMCS's currency and set conversion rates from within the Admin Area.

You can access this feature at Configuration () > System Settings > Currencies, or, prior to WHMCS 8.0, Setup > Payments > Currencies.

Watch the video tutorial for this feature

Currencies

The list of currencies displays all of the currently-configured currencies on your WHMCS installation.

Default Currency

By default, the base currency on new WHMCS installations is USD.

Do not attempt to change the default currency for WHMCS installations that already include invoice or transaction data. Instead, add the desired currency to your installation.

If your installation does not contain any transaction or invoice data, you can change this by selecting the country for that currency in the General tab at Configuration () > Setup Wizard.

The system will attempt to set your default currency to the correct currency for that region.
For more information, see Changing the Default Currency.

Watch the video tutorial for this feature

Currency Configuration

For each currency, you can configure the following settings:

Currency Code — The standard three-letter ISO-4217 code that payment gateways use.
Prefix — The text or symbol to display before the amount.
Suffix — The text or symbol to display after the amount.
Format — The format style for currencies (see below).
Base Conv. Rate — The rate by which to divide amounts in this currency to get to the base currency (for more information and steps to calculate this, see below). For example, USD to GBP could be 1.5.
WHMCS 8.0 includes improved currency support to allow you to enter larger numbers, up to 99 trillion (14 to the left of the decimal and 2 to the right). This allows you to easily work with currencies with large values like Indonesian Rupiahs (IDR), which are (at the time of this document's writing) valued at 14,830.85 IDR to 1 USD.

Add a Currency

To add a new currency, enter the desired information under Add Additional Currency and click Add Currency.

Edit a Currency

To edit an existing currency, click the appropriate Edit icon, make the desired changes, and click Save Changes.

If you updated the conversion rate, you can select Update Pricing to recalculate the prices in this currency using the new rate.

Currency Format

You can choose a currency format to match the styling customs of monetary amounts in different currencies.

The following non-decimal currencies must use the 1,234 currency format:

BYR, BIF, CLP, KMF, DJF', HUF, ISK,
JP', MGA, PYG, RWF, KRW, VUV

Base Conversion Rate

You must set a base conversion rate for each currency that you add to WHMCS.

You cannot edit the base conversion rate for the default currency.

To calculate the base conversion rate to enter for Base Conv. Rate:

Go to The Universal Currency Converter.
Select your default currency in From this currency. This is the default currency for your WHMCS installation, which is usually USD.
Select your second currency from To this currency. This is the currency that you are currently adding or editing. For example, this could be GBP.
Click Go. The base conversion rate will appear as a conversion of 1 of the default currency to an amount in the second currency. For example:

In this example, you would enter 0.81979239 for Base Conv. Rate while creating or editing a GBP currency.

Specifying Currency in a Link

You can link to the order form with a specific currency by adding the required actions to the URL. For example, cart.php?currency=1 or cart.php?currency=2.

Update Exchange Rates

WHMCS uses the ECB API to retrieve exchange rates. Only the currencies listed below are supported for Auto Updating Rates.

WHMCS can retrieve and update the base conversion rate values daily for the following currencies:

USD, EUR, JPY, BGN, CZK, DKK, GBP, HUF, PLN, RON, SEK, CHF, ISK, NOK, HRK, TRY, AUD, BRL, CAD, CNY, HKD, IDR, ILS, INR, KRW, MXN, MYR, NZD, PHP, SGD, THB, and ZAR

For a full list of international currency codes, see ISO-4217.

You can manually sync these rates by clicking Update Exchange Rates or you can configure updates via the daily cron at Configuration () > System Settings > Automation Settings, or, prior to WHMCS 8.0, Setup > Automation Settings.

Update Product Prices

You can automatically update prices in currencies other than the base rate using the rates you set.

To do this manually, click Update Product Prices or set this to run after the daily rates update at Configuration () > System Settings > Automation Settings or, prior to WHMCS 8.0, Setup > Automation Settings.

Troubleshooting

Exchange Rates Update Results - Update Failed for MAD Exchange Rate

You may encounter this error if the currency is not a supported currency for automatically updating exchange rates (see above). Make certain that you are using a supported currency or, if the currency is unsupported, edit the Base Conversion Rate manually.

@@ Line 1: / Line 1: @@
-You can configure the currencies you wish to use in your WHMCS installation in Setup > Currencies
+WHMCS supports all global currencies as well as syncing of product prices across currencies. Currency support applies to all currency values throughout WHMCS (for example, product and addon pricing). You can change WHMCS's currency and set conversion rates from within the Admin Area.
+You can access this feature at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > Currencies''', or, prior to WHMCS 8.0, '''Setup > Payments > Currencies'''.
-By default the base currency will be USD.  This can be edited and should be changed to your home currency if not USD.  You can then add additional currencies to run alongside that.
+<html><a href="http://www.youtube.com/watch?v=LFTVqImvPHw&hd=1" class="docs-video-tutorial"><em>Watch the video tutorial for this feature</em><span> <img src="https://assets.whmcs.com/icons/youtube.png"> </span></a></html>
-'''Video Setup Guide:''' http://www.whmcs.com/tutorials.php?i=0<br />
+== Currencies ==
-'''Change Default Currency:''' http://whmcs.com/tutorials.php?i=10
-==Adding/Editing a Currency==
+The list of currencies displays all of the currently-configured currencies on your WHMCS installation.
-The fields for adding or editing a currency are the same.  Below is an explanation of each of these:
+=== Default Currency ===
-*Currency Code – This should be the standard 3 letter ISO 4217 code used by gateways
+By default, the base currency on new WHMCS installations is USD.
-*Prefix – The text/symbol to display before the amount
-*Suffix – The text/symbol to display after the amount
-*Format – Allows you to choose between the different format styles for currencies
-*Base Conv. Rate – The rate amounts in this currency should be divided by to get to the base currency, eg. USD to GBP currently 1.5
-The first currency is the default one. If you want to define a default currency you must to edit the currency code, and set it to the new default currency.
+<div class="docs-alert-danger">
+'''Do not''' attempt to change the default currency for WHMCS installations that already include invoice or transaction data. Instead, add the desired currency to your installation.
+</div>
-==Auto Updating Rates==
+If your installation '''does not''' contain any transaction or invoice data, you can change this by selecting the country for that currency in the '''General''' tab at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > Setup Wizard'''.
-WHMCS has the built in capability to retrieve and update the base conversion rate values daily for the following currencies:
+* The system will attempt to set your default currency to the correct currency for that region.
+* For more information, see [https://help.whmcs.com/m/payments/l/1122770-changing-the-default-currency Changing the Default Currency].
+<html><a href="https://www.youtube.com/watch?v=Px1WjlmGDLw&hd=1" class="docs-video-tutorial"><em>Watch the video tutorial for this feature</em><span> <img src="https://assets.whmcs.com/icons/youtube.png"> </span></a></html>
-USD, EUR, JPY, BGN, CZK, DKK, EEK, GBP, HUF, LTL, LVL, PLN, RON, SEK, CHF, NOK, HRK, RUB, TRY, AUD, BRL, CAD, CNY, HKD, IDR, INR, KRW, MXN, MYR, NZD, PHP, SGD, THB & ZAR
+=== Currency Configuration ===
-For a full list of international currency codes: [http://en.wikipedia.org/wiki/ISO_4217]
+For each currency, you can configure the following settings:
-You can manually request the rates to be synced using the Update Exchange Rates button on the currencies page or you can configure it to be automated with the daily cron in Config > Automation Settings.
+* '''Currency Code''' — The standard three-letter ISO-4217 code that payment gateways use.
+* '''Prefix''' — The text or symbol to display before the amount.
+* '''Suffix''' — The text or symbol to display after the amount.
+* '''Format''' — The format style for currencies ([[#Currency_Format|see below]]).
+* '''Base Conv. Rate''' — The rate by which to divide amounts in this currency to get to the base currency (for more information and steps to calculate this, [[#Base_Conversion_Rate|see below]]). For example, USD to GBP could be 1.5. <div class="docs-alert-info">WHMCS 8.0 includes improved currency support to allow you to enter larger numbers, up to 99 trillion (14 to the left of the decimal and 2 to the right). This allows you to easily work with currencies with large values like Indonesian Rupiahs (IDR), which are (at the time of this document's writing) valued at 14,830.85 IDR to 1 USD.</div>
-==Auto Updating Prices==
+==== Add a Currency ====
-WHMCS also provides the ability to have the prices in currencies other than the base rate automatically updated based on the rates set.  Again you can invoke that manually from the currencies page with the “Update Product Prices” button or you can have it run after the daily rates update in Config > Automation Settings.
+To add a new currency, enter the desired information under '''Add Additional Currency''' and click '''Add Currency'''.
-==Specifying Currency in a link==
+==== Edit a Currency ====
-You can link to the order form with a specific currency by simulating what the form shown for currency selection does - eg. cart.php?currency=1 cart.php?currency=2
+To edit an existing currency, click the appropriate '''Edit''' icon, make the desired changes, and click '''Save Changes'''.
+If you updated the conversion rate, you can select '''Update Pricing''' to recalculate the prices in this currency using the new rate.
+==== Currency Format ====
+You can choose a currency format to match the styling customs of monetary amounts in different currencies.
+The following non-decimal currencies '''must''' use the ''1,234'' currency format:
+ BYR, BIF, CLP, KMF, DJF', HUF, ISK,
+ JP', MGA, PYG, RWF, KRW, VUV
+==== Base Conversion Rate ====
+You must set a base conversion rate for each currency that you add to WHMCS.
+<div class="docs-alert-warning">
+You cannot edit the base conversion rate for the default currency.
+</div>
+To calculate the base conversion rate to enter for '''Base Conv. Rate''':
+# Go to [http://www.xe.com/ucc/ The Universal Currency Converter].
+# Select your default currency in '''From this currency'''. This is the default currency for your WHMCS installation, which is usually USD.
+# Select your second currency from '''To this currency'''. This is the currency that you are currently adding or editing. For example, this could be GBP.
+# Click '''Go'''. The base conversion rate will appear as a conversion of <tt>1</tt> of the default currency to an amount in the second currency. For example:[[Image:Bcr1.png|650px]]
+In this example, you would enter <tt>0.81979239</tt> for '''Base Conv. Rate''' while creating or editing a <tt>GBP</tt> currency.
+=== Specifying Currency in a Link ===
+You can link to the order form with a specific currency by adding the required actions to the URL. For example, <tt>cart.php?currency=1</tt> or <tt>cart.php?currency=2</tt>.
+== Update Exchange Rates ==
+<div class="docs-alert-info">
+WHMCS uses the ECB API to retrieve exchange rates. Only the currencies listed below are supported for Auto Updating Rates.
+</div>
+WHMCS can retrieve and update the base conversion rate values daily for the following currencies:
+ USD, EUR, JPY, BGN, CZK, DKK, GBP, HUF, PLN, RON, SEK, CHF, ISK, NOK, HRK, TRY, AUD, BRL, CAD, CNY, HKD, IDR, ILS, INR, KRW, MXN, MYR, NZD, PHP, SGD, THB, and ZAR
+For a full list of international currency codes, see [http://en.wikipedia.org/wiki/ISO_4217 ISO-4217].
+You can manually sync these rates by clicking '''Update Exchange Rates''' or you can configure updates via the daily cron at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]''', or, prior to WHMCS 8.0, '''Setup > Automation Settings'''.
+== Update Product Prices ==
+You can automatically update prices in currencies other than the base rate using the rates you set.
+To do this manually, click '''Update Product Prices''' or set this to run after the daily rates update at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Automation Settings]]''' or, prior to WHMCS 8.0, '''Setup > Automation Settings'''.
+== Troubleshooting ==
+'''Exchange Rates Update Results - Update Failed for MAD Exchange Rate'''
+You may encounter this error if the currency is not a supported currency for automatically updating exchange rates (see above). Make certain that you are using a supported currency or, if the currency is unsupported, edit the '''Base Conversion Rate''' manually.

Documentation