Important

This article refers to the Currency Switcher for Easy Digital Downloads. That plugin was retired in 2021 and it's no longer available for purchase. If you're looking for the documentation for the Aelia Currency Switcher for WooCommerce, please refer to the following article: https://aelia.freshdesk.com/a/solutions/articles/3000048680.


Integrating with our Currency Switcher is quite straightforward, and it involves calling two filters provided by our plugins. One filter provides access to the automatic conversion function, while the other returns a list of the enabled currencies. By using filters, the integration will be transparent: when the Currency Switcher is not installed, your plugin will works as it does normally (no currency conversion will be performed, the values passed to the filters will be returned as normal). Thanks to this architecture, you won't have to add conditions to check if the plugin is installed, or call specific currency conversion functions. 


The integration with our plugin can be implemented in two ways:

  • A basic integration introduces automatic conversion of all currency prices, using exchange rates.
  • An advanced integration, with per-currency pricing, requires more work, as you have to add new fields to allow customers to enter prices in multiple currencies, but it will give your users greater flexibility.

Our suggestion is to start with a basic integration and move to an advanced one once you are comfortable with the aspects of multi-currency development. You can find an example of both integrations below.


Basic integration

Code example: https://pastebin.com/JWe5ZYfy


A basic integration with our Currency Switcher requires a couple of lines of code. The integration can be summarised as follows: when admin enter a price (e.g. 10 USD, where "USD" is the shop base currency), you simply have to pass the amount to the conversion functions before using it, and the Currency Switcher will take care of the calculations.


Generally, any amount that was entered in shop's base currency has to be passed to the Currency Switcher for conversion, before being processed further by your plugin. The modification consists in adding one single step (in bold, below) to the logic you have now:

  1. A price is entered in base currency in the backend.
  2. When you need to use the price, load it from the database.
  3. Pass the price to the currency conversion filter.
  4. Use the price as you do now.


You can find the code to invoke the currency conversion logic here, ready to copy/paste in your plugin: https://pastebin.com/JWe5ZYfy.

 

Advanced integration - Per-currency pricing (optional, but recommended)

Code example: https://pastebin.com/NaKTg3eC


Out of the box, the Currency Switcher handles prices of products in multiple currencies. That is, instead of setting a product price to 100 USD and having EUR, GBP and so calculated automatically, it's possible to enter a price for each currency, such as 100 USD, 200 EUR, 300 GBP. Conversion rates are ignored, and the manually entered prices are used instead.


To provide a more comprehensive set of features, you might be interested in considering the possibility of adding such feature to your plugin as well. For example, you could allow customers to enter prices as follows:

  • USD: 100
  • EUR: 95
  • GBP: 90

 

This, of course, is an example that refers to a generic product. The same logic would apply to your custom pricing fields, for example sale prices, addons, fees, shipping costs, renewals, etc. 

Per-currency pricing is one of the most requested features for all multi-currency plugins, and, although it would require some more changes, it should be fairly straightforward to implement. Here's the summary of the changes:

  1. In the user interface, instead of one set of price fields (regular price, sale price, etc), display one set per currency. The Currency Switcher can give you the list of enabled currencies with one line of code.
  2. Validate, save and load all the prices. For example, instead of $price, $sale_price, $shipping_cost, you would have

    - $price_USD
    - $sale_price_USD
    - $shipping_cost_USD
    - $price_EUR
    - $sale_price_EUR
    - $shipping_cost_EUR
    - $price_GBP
    - $sale_price_GBP
    - $shipping_cost_GBP

    And so on. Showing the prices on the Admin UI, storing and retrieving them will be up to your plugin. You can use any logic you like, remaining independent from our Currency Switcher implementation. When you will save the prices, you will just have to associate the values to the appropriate currency, so that you will be able to retrieve the prices correctly. For example, you can store the prices in shop base currency with "generic" meta keys:
    - _price
    - _sale_price
    - _shipping cost

    And the prices in additional currencies in custom meta:
    - _price_EUR
    - _sale_price_EUR
    - _shipping_cost_EUR

    This will allow the plugin logic to remain the same for both single currency and multi-currency setups. In single currency scenarios, the generic meta will be used (like it happens now). In multi-currency scenarios, the generic meta will be used for the shop base currency, and the currency-specific meta for all other currencies.

  3. The conversion method described in the Basic Integration section requires a minimal modification to support extra prices. You can find an example here: https://pastebin.com/NaKTg3eC (note the additional $prices_per_currency argument). The call to the conversion method should pass the array of currency amounts as well (ref. #2 above), so that the method can pick them up automatically. When an amount is not passed for a currency (e.g. if the AUD price is left empty, like in the example), then the automatic conversion will take place.


Both the above integrations will allow for a loose coupling with the Currency Switcher. As anticipated, everything in your plugin will work fine whether our Currency Switcher is installed or not:

  • When our plugin is installed, you will have to show, load and save prices for each of the available currencies (e.g. USD, EUR, GBP).
  • When our plugin is not installed, the enabled_currencies() method will still return an array of currencies, which only contains one currency (the base one). All conversion functions will return you the same value you pass to them (i.e. no conversion will occur).


Should you have any questions, or need any clarification, please feel free to contact us. We will be happy to provide you with all information you need to implement your integration.