MHM Currency Switcher adds multi-currency support to your WooCommerce store. Customers can browse products, add items to their cart, and complete checkout in their preferred currency with real-time exchange rates.<\/p>\n\n
Key Features<\/strong><\/p>\n\n Cache compatibility mode<\/strong><\/p>\n\n A page cache stores the HTML your server produced for whoever asked first. When\nprices are converted on the server, that means the first visitor's currency is\nwhat every later visitor is served. Cache compatibility mode, which is on by\ndefault, avoids this: anonymous shop, archive and product pages are rendered in\nyour base currency, so the same cached page is correct for everyone, and the\nbrowser converts the prices it can see afterwards through a REST request to this\nplugin.<\/p>\n\n The split is deliberate. Only displayed<\/em> prices are converted in the browser.\nCart, checkout, order totals, order emails and the WooCommerce REST API are\nalways calculated on the server in the currency the customer actually chose, so\nthe amount charged cannot be altered from the browser.<\/p>\n\n You can switch the mode off under WooCommerce > MHM Currency >\nAdvanced<\/strong>, in which case prices are converted on the server as they were before\nthis feature existed. Read \"Known limits\" below before deciding either way \u2014\nboth settings have consequences, and they are different ones.<\/p>\n\n These are consequences of how cache compatibility mode works, not defects. They\nare listed so you can decide with your eyes open.<\/p>\n\n Three fixes sit above the setting and stay in place whether it is on or off:\nprices are no longer converted on admin screens or in admin AJAX (which used to\nwrite a converted price into an order line item), With the mode on, the page a crawler fetches has not been through the browser,\nso it carries base-currency prices, and so does the machine-readable product data\nin it. See the structured data question above; the mismatch is deliberate.<\/p>\n\n The page arrives with your base-currency prices already on screen \u2014 nothing is\nhidden waiting for JavaScript \u2014 and the browser swaps in the converted ones as\nsoon as its request comes back, each price fading over 200ms as it changes. On a\nslow connection the base price is readable for longer before the swap. Visitors\nwho have asked their system for reduced motion get the swap without the fade.<\/p>\n\n Nothing breaks and no error is shown to the visitor \u2014 the page simply keeps the\nbase-currency prices it was rendered with, and the reason is written to the\nbrowser console. Cart and checkout are unaffected, because they never depended\non the browser in the first place.<\/p>\n\n On a cacheable page the plugin forces WooCommerce to fetch variation prices over\nAJAX, because the variations JSON WooCommerce would otherwise embed in the page\ncarries base-currency prices that its own scripts write straight into the page.\nThe cost is one request when a visitor picks a variation, and that\n data-product_variations is A mini-cart is rendered on every page, so it cannot be classified per request.\nIt is rendered in the base currency and then corrected by WooCommerce's own cart\nfragment refresh, which is a server-side conversion. If cart fragments are\ndisabled on your site \u2014 some themes and optimisation plugins dequeue them \u2014 the\ncached mini-cart total stays in the base currency while the rest of the page\nconverts. The plugin watches for this and says so in the admin when it happens;\na site with no mini-cart at all is never warned about it.<\/p>\n\n Page caches exclude cart and checkout automatically because they recognise the\npages WooCommerce assigned. If you have put a cart or checkout shortcode or block\non some other page, exclude that page yourself. Two things go wrong otherwise:\nthe conversion decision flips to \"convert\" partway through the render, so the\nrest of the page is printed already converted and without the markers the browser\nlooks for, and blocks-based cart and checkout embed their amounts in the page as\nJSON while rendering. Either way the first visitor's currency is what the cache\nthen hands to everyone. Cart contents are personal anyway; such a page should not\nbe cached.<\/p>\n\n A currency can be requested in the URL, and a cache treats every distinct URL as\na separate entry, so linking to A An order is stored in the currency the customer paid in, and WooCommerce\nAnalytics reports every order's figures in your store currency without\nconverting them back. A 4.38 USD order is counted as 4.38 in your base\ncurrency, so once you take orders in more than one currency the revenue\nfigures in Analytics, and the totals in the customer panel on the order\nscreen, are sums of unlike amounts. The orders themselves are correct \u2014 each\none keeps its own currency, total and the exchange rate it was placed at, and\nthis plugin stores that rate on the order. It is the aggregate reports that\ncannot be read as money. Nothing in this plugin can fix that from the outside;\nif you need accurate multi-currency reporting, export the orders and convert\nthem using the rate recorded on each one.<\/p>\n\n Logged-in visitors take the server-side path, which is correct as long as your\ncache does what nearly all of them do and never serves cached pages to logged-in\nusers. An edge cache or CDN configured to cache without looking at cookies is the\nexception, and there a logged-in visitor's converted page can be stored and\nserved on. If you cache at the edge, confirm it varies on the login cookie.<\/p>\n\n This plugin connects to two third-party services to keep currency conversion\nrates up to date. What each one is sent, and when, is described separately\nbelow because the two are not the same. Both requests are made with PHP's\n WP_Http transport, which in WordPress's default configuration sends a\n User-Agent header of the form ExchangeRate-API<\/strong><\/p>\n\n What it is: a commercial exchange-rate API, used as the primary source of\nexchange rates.<\/p>\n\n What is sent, and when: the three-letter base currency code you have\nconfigured (for example Terms of service and privacy policy: https:\/\/www.exchangerate-api.com\/terms\n(ExchangeRate-API publishes its privacy policy inside that same page rather\nthan on a separate one.)<\/p>\n\n European Central Bank (ECB) daily reference rates<\/strong><\/p>\n\n What it is: the ECB's public daily reference-rate feed, used as the fallback\nwhen ExchangeRate-API cannot be reached.<\/p>\n\n What is sent, and when: nothing beyond the User-Agent described above. The\nfeed is a fixed, parameter-free address --\n https:\/\/www.ecb.europa.eu\/stats\/eurofxref\/eurofxref-daily.xml -- so no\ncurrency code or other value is sent to the ECB; the same document is\nreturned to every requester. It is only requested when ExchangeRate-API's\nrequest has failed. The feed is EUR-based and covers roughly thirty\ncurrencies rather than the hundreds ExchangeRate-API carries. If your base\ncurrency is outside that set, this source returns nothing at all and your\nexisting rates are left unchanged until the next attempt; if only one of\nyour configured target currencies is outside that set, the other target\ncurrencies still update and the unsupported one is simply left without a\nrate from this source.<\/p>\n\n The ECB does not publish a document titled \"Terms of Service.\" Its terms of\nuse are stated on its Disclaimer & Copyright page, which is the closest\nequivalent and is linked below.<\/p>\n\n Disclaimer & Copyright (terms of use): https:\/\/www.ecb.europa.eu\/services\/using-our-site\/disclaimer\/html\/index.en.html\nPrivacy statement: https:\/\/www.ecb.europa.eu\/services\/data-protection\/privacy-statements\/html\/ecb.privacy_statement_website.en.html<\/p>\n\n The ECB's reference-rates page separately states that using these rates for\ntransaction purposes is strongly discouraged:\nhttps:\/\/www.ecb.europa.eu\/stats\/policy_and_exchange_rates\/euro_reference_exchange_rates\/html\/index.en.html\nThat page, not the two links above, is the source of that caution. This\nplugin uses the feed to convert prices for display and checkout, which is\nthe kind of transactional use that notice is about; if that matters for your\nshop, review that page before relying on this fallback.<\/p>\n\n Redirecting a source<\/strong><\/p>\n\n If your network blocks the ECB feed, the Visitor geolocation (through WooCommerce)<\/strong><\/p>\n\n When \"Enable geolocation-based currency detection\" is switched on, the plugin\nasks WooCommerce which country a visitor is in, using WooCommerce's own\n WC_Geolocation API. Depending on how your site is configured, WooCommerce\nanswers that either from a local MaxMind database or by contacting the remote\ngeolocation service it is configured to use \u2014 the request and the service are\nWooCommerce's, not this plugin's, and this plugin sends nothing itself. The\nsetting is off unless you turn it on.<\/p>\n\n WooCommerce geolocation documentation:\nhttps:\/\/woocommerce.com\/document\/maxmind-geolocation-integration\/<\/p>\n\n The settings screen is a React application, and what ships inside the plugin is\nthe compiled bundle at Full source, including the unminified JavaScript:\nhttps:\/\/github.com\/MaxHandMade\/mhm-currency-switcher<\/p>\n\n The source of the bundle is That writes [mhmcs_currency_switcher] renders the currency dropdown. It accepts one\nattribute, Its attributes are all optional:<\/p>\n\n Both are also available as Elementor widgets.<\/p><\/dd>\n As many as your shop needs \u2014 every currency WooCommerce offers can be enabled,\nand nothing is held back for a paid version. The REST API refuses a request\ncarrying more than 500 currency rows; that is a guard against oversized payloads\nand is well above the number of codes WooCommerce itself offers, so the panel\ncannot reach it.<\/p><\/dd>\n Exchange rates are fetched from ExchangeRate-API in real time, either on demand or on a schedule you configure (hourly, twice daily, or daily) so your rates stay current without manual intervention.<\/p>\n\n If that source cannot be reached, the plugin falls back to the European Central Bank's daily reference rate feed before giving up and leaving your existing rates in place. Both are named, with their terms, under \"External services\" below. If your network blocks the fallback, the Yes. MHM Currency Switcher fully supports WooCommerce High-Performance Order Storage (HPOS \/ Custom Order Tables).<\/p><\/dd>\n No. A fixed price is stored per product and currency, not per price type, so the same amount is used for the regular price and the sale price. A product on sale in your base currency shows as not on sale in a currency you have given a fixed price to. If you need the sale to carry across, leave that currency to the exchange rate instead of fixing it.<\/p><\/dd>\n Yes. When cache compatibility mode is on, prices on cached pages are converted through a public REST endpoint, and one address may call it 120 times a minute by default. Ordinary browsing is nowhere near that \u2014 a page makes one request. If your shop sits behind a reverse proxy or a CDN that makes every visitor look like the same address, raise or disable the limit with the Some themes and plugins define WooCommerce's cart constant on every page, usually to show a cart total in the header. When that happens the plugin treats every page as a checkout \u2014 the customer's money is at stake \u2014 and converts prices on the server, which is exactly what cache compatibility mode exists to avoid. Nothing looks wrong on the site: prices are still correct for whoever loads the page first, and then a page cache can serve that person's currency to everyone else. Because there is no visible symptom, the plugin says so in the admin instead. The notice clears itself as soon as a front-end page renders normally again.<\/p><\/dd>\n With cache compatibility on, the page is generated in your base currency and the browser converts the prices afterwards, so the machine-readable product data a crawler reads stays in the base currency. This is deliberate and is not corrected: pinning it the other way would leave the data disagreeing with the page in the one case where the two currently agree \u2014 with cache compatibility switched off, where the page and the structured data are both converted on the server.<\/p><\/dd>\n Only when the request asks for a currency: One known limit: the \n
Known limits<\/h3>\n\n
Turning the mode off does not restore the exact 1.0.0 behaviour<\/h4>\n\n
wc\/v3<\/code> REST reads are pinned\nto the base currency, and scheduled tasks and WP-CLI no longer convert. Switching\nthe mode off restores the 1.0.0 display<\/em> behaviour \u2014 prices converted on the\nserver \u2014 and nothing else.<\/p>\n\nSearch engines and crawlers see your base prices<\/h4>\n\n
Converted prices replace the base ones a moment after the page appears<\/h4>\n\n
With JavaScript disabled, or the endpoint unreachable, base prices stay<\/h4>\n\n
Variable products make one extra request, and some swatch plugins lose the price<\/h4>\n\n
false<\/code>: third-party colour or size swatch plugins\nthat read prices out of that JSON instead of asking WooCommerce may stop showing\na price. If you use such a plugin, check a variable product before going live.<\/p>\n\nThe mini-cart relies on WooCommerce cart fragments<\/h4>\n\n
A cart or checkout on a page WooCommerce does not know about must be excluded from your cache<\/h4>\n\n
`?currency=` multiplies your cache entries<\/h4>\n\n
?currency=EUR<\/code> and ?currency=GBP<\/code> stores the\nsame page more than once. The switcher itself does not produce these URLs \u2014 it\nwrites a cookie and leaves the address alone. On a cached page it converts the\nprices where they stand; on the cart page, for a logged-in visitor, or with\ncache compatibility switched off, it reloads instead. Either way the URL is the\none the visitor was already on, so no extra cache entry is created.<\/p>\n\n?currency=<\/code> link also applies to that page view only: it deliberately sets no\ncookie, so the next page the visitor opens is back in your base currency unless\nthey use the switcher. That is not an oversight \u2014 a link that silently pinned a\ncurrency could show one currency in the catalogue while the cart, which reads\nthe cookie, charged another. If you want a campaign link that sticks, send\nvisitors to a page carrying the switcher rather than relying on the parameter.<\/p>\n\nWooCommerce Analytics adds different currencies together<\/h4>\n\n
Logged-in visitors are converted on the server<\/h4>\n\n
External services<\/h3>\n\n
WordPress\/{version}; {your site's URL}<\/code> --\nso the site's own address leaves with every request to either service, not\njust the data described below. That header is filterable\n(http_headers_useragent<\/code>, http_request_args<\/code>), so a site that has changed\nit will send something different.<\/p>\n\nUSD<\/code>), sent as part of the request URL --\n https:\/\/api.exchangerate-api.com\/v4\/latest\/{BASE_CURRENCY} -- when you\npress \"Sync rates\" in the admin panel, when you run wp mhmcs rates-sync<\/code>\nfrom the command line, and on the schedule you configure under automatic\nrate updates (hourly, twice daily, or daily). No other data from your site\nis included.<\/p>\n\nmhmcs_fallback_rates_url<\/code> filter\nreceives the URL, the base currency code and which source is being filtered\n-- always 'ecb'<\/code>, since ECB is now the only fallback -- so the request can\nbe pointed elsewhere.<\/p>\n\nSource code<\/h3>\n\n
admin-app\/build\/index.js<\/code>. The readable source it is\nbuilt from is not in the package, so here is where to find it and how to\nreproduce the build.<\/p>\n\nadmin-app\/src\/<\/code>. It is compiled with WordPress's\nown build tooling, @wordpress\/scripts, and nothing else:<\/p>\n\nnpm install\nnpm run build\n<\/code><\/pre>\n\nadmin-app\/build\/index.js<\/code> together with the index.asset.php<\/code>\ndependency map the plugin reads when enqueuing the script. No other build step,\nminifier or bundler is involved, and no code is generated at install time or at\nruntime.<\/p>\n\n\n\n
mhm-currency-switcher<\/code> folder to the \/wp-content\/plugins\/<\/code> directory, or install directly through the WordPress plugin screen.<\/li>\n\n
What are the shortcodes?<\/h3><\/dt>\n
size<\/code>, which may be small<\/code>, medium<\/code> or large<\/code>; leave it out to\nuse the size saved in Display Options.<\/p>\n\n[mhmcs_currency_prices] renders the same product price in several currencies.\n<\/code><\/pre>\n\n\n
currencies<\/code> \u2014 comma-separated codes, e.g. currencies=\"USD,EUR\"<\/code>. Without\nit, the currencies chosen in Display Options are used. Codes you have not\nconfigured as currencies are ignored.<\/li>\nproduct_id<\/code> \u2014 price a specific product instead of the one being viewed.<\/li>\nprice<\/code> \u2014 price a specific amount instead of a product's.<\/li>\nshow_flags<\/code> \u2014 true<\/code> or false<\/code>, overriding the saved Display Options\nsetting.<\/li>\n<\/ul>\n\nHow many currencies can I add?<\/h3><\/dt>\n
How are exchange rates fetched?<\/h3><\/dt>\n
mhmcs_fallback_rates_url<\/code> filter can point it somewhere else.<\/p><\/dd>\nIs the plugin compatible with WooCommerce HPOS?<\/h3><\/dt>\n
Can a per-product fixed price be a sale price?<\/h3><\/dt>\n
Is there a limit on how often the conversion endpoint can be called?<\/h3><\/dt>\n
mhmcs_convert_rate_limit<\/code> filter. Note that the address is read from the proxy headers WooCommerce passes on, which it trusts unconditionally and which can be forged; the limit bounds accidental hammering rather than a determined attacker.<\/p><\/dd>\nI see a warning that cache compatibility is not being applied. What is it?<\/h3><\/dt>\n
Why does the structured data show a different currency from the price on the page?<\/h3><\/dt>\n
Does the WooCommerce REST API return converted prices?<\/h3><\/dt>\n
?currency=EUR<\/code> on a wc\/v3<\/code> product request converts price<\/code>, regular_price<\/code> and sale_price<\/code> and adds a currency_code<\/code> field. Without the parameter the response is pinned to your base currency, so the answer never depends on the cookies of whoever is calling. A per-product fixed price takes precedence over the exchange rate here, exactly as it does on the shop page.<\/p>\n\nprice_html<\/code> field is not pinned in the same way. It cannot be reached in that state by a normal wc\/v3<\/code> client \u2014 only by code that dispatches an internal REST request during a page render \u2014 so no integration sees it, but it is not consistent with the three numeric fields and is recorded here rather than left unsaid.<\/p><\/dd>\n\n<\/dl>\n\n\n2.1.0<\/h4>\n\n
\n
mhm-cs-*<\/code> to mhmcs-*<\/code>.\nEvery class in the switcher's CSS and JS -- .mhm-cs-switcher<\/code>,\n .mhm-cs-dropdown, .mhm-cs-size--small<\/code>, and the rest -- now uses the\n mhmcs- prefix instead. If you have written custom CSS or JavaScript\nthat targets one of the old mhm-cs-*<\/code> classes, it will stop matching\nafter you update: change your selectors to the new mhmcs-<\/code> names. No\nalias is kept for the old classes.<\/li>\nmhmcs_fallback_rates_url<\/code> filter's $source<\/code> argument is\nnow always ecb<\/code>. The exchange-rate fallback no longer has two stages\n(currency-api<\/code> then frankfurter<\/code>); it is now a single request to the\nEuropean Central Bank's daily reference feed. Code that checked for\n $source === 'currency-api' or 'frankfurter'<\/code> will no longer see those\nvalues.<\/li>\ncurrency-api.pages.dev<\/code> then\nFrankfurter chain added in 2.0.0. Coverage is unchanged -- the same\nroughly thirty currencies -- because that was already the final stage of\nthe old chain; the extra intermediate stage is removed as no longer\nuseful.<\/li>\nactivate_plugins<\/code> (the capability to\nact on it -- you install a plugin), and the two cache-compatibility\nnotices need manage_woocommerce<\/code>.<\/li>\nmhm-cs-<\/code> \/ mhm_cs_<\/code> \/ mhm_currency_switcher_<\/code>\nlegacy naming token still in the plugin -- across CSS, JavaScript, the\nadmin panel source and its compiled build, tests and documentation -- has\nbeen renamed to the current mhmcs<\/code> prefix. This is the last of the\nprefix cleanup that started with the 2.0.0 shortcode and option rename.<\/li>\nGET \/rates<\/code> REST endpoint was\nremoved. It duplicated information already visible in the page itself;\nthe authenticated \/rates\/sync<\/code> and \/rates\/preview<\/code> endpoints used by\nthe admin panel are unaffected.<\/li>\nlanguages\/<\/code> is no longer included in the release ZIP --\nWordPress.org compiles translations from the .pot<\/code> file, which is still\nkept in the plugin's repository.<\/li>\n<\/ul>\n\n2.0.0<\/h4>\n\n
\n
[mhm_currency_switcher]<\/code>\nis now [mhmcs_currency_switcher]<\/code>, and [mhm_currency_prices]<\/code> is now\n [mhmcs_currency_prices]. The old tags are gone; a page still holding one\nwill show the raw text instead of the switcher, so update any page, post or\ntemplate that uses them. WordPress.org's prefix check splits a prefix at the\nfirst underscore, which read the old tags as \"mhm\" -- three letters, under\nthe four-letter minimum -- and a plugin cannot be reviewed under a name the\nreview tool cannot attribute to it. Stored data is untouched: option names,\norder meta and per-product fixed prices all keep the names they had.<\/li>\nlatest.currency-api.pages.dev<\/code> instead of the\njsDelivr CDN. Same upstream project, same payload; only the host changed.\nWordPress.org's review tool keeps a fixed list of public CDN domains and\ntreats a shipped source naming one as an error, whatever the URL fetches.\nIf your store restricts outbound requests to an allow-list, permit the new\nhost -- or redirect it with the filter below.<\/li>\nmhmcs_fallback_rates_url<\/code>, which receives the URL, the base\ncurrency code and which source is being filtered (currency-api<\/code> or\n frankfurter), so a store can move one source without moving the others.<\/li>\nintl<\/code> extension is required.<\/li>\n1.3.1<\/h4>\n\n
\n
?currency=<\/code>, while\nevery other field in the response, and the currency a client reads it under,\nstayed in the base currency. Feeds, stock syncs and marketplace integrations\ntook that price as fact.<\/li>\n\n
1.3.0<\/h4>\n\n
\n
GET \/settings<\/code> returned the whole stored option, including keys whose\ncontrols were removed in an earlier release. One of them, provider_api_key<\/code>,\nis a credential you supplied. Saving settings has always dropped those keys,\nbut a shop that had not pressed Save since then still held the value, and the\nread route handed it to anyone with the \"manage WooCommerce\" capability \u2014\nwhich includes shop managers, who are not administrators. The read route now\nfilters the same list the save route and the uninstaller do.<\/li>\n1.2.0<\/h4>\n\n
\n
1.1.3<\/h4>\n\n
\n
[mhm_currency_switcher]<\/code> and [mhm_currency_prices]<\/code>\nshortcodes and their attributes, which this file advertised but never named.<\/li>\n1.1.2<\/h4>\n\n
\n
1.1.1<\/h4>\n\n
\n
1.1.0<\/h4>\n\n
\n
wc\/v3<\/code> REST reads now return the base currency unless the request\nasks for one, so the response no longer depends on the caller's cookies.<\/li>\nPOST mhmcs\/v1\/convert<\/code>, rate limited to 120\nrequests a minute per address (mhmcs_convert_rate_limit<\/code> filter).<\/li>\n1.0.0<\/h4>\n\n
\n
mhmcs<\/code> prefix. Settings from earlier\ndevelopment builds are not carried over.<\/li>\n<\/ul>","raw_excerpt":"Multi-currency support for WooCommerce. Let your customers browse, shop, and checkout in their preferred currency with real-time exchange rates.","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/wordpress.org\/plugins\/wp-json\/wp\/v2\/plugin\/359893","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/wordpress.org\/plugins\/wp-json\/wp\/v2\/plugin"}],"about":[{"href":"https:\/\/wordpress.org\/plugins\/wp-json\/wp\/v2\/types\/plugin"}],"replies":[{"embeddable":true,"href":"https:\/\/wordpress.org\/plugins\/wp-json\/wp\/v2\/comments?post=359893"}],"author":[{"embeddable":true,"href":"https:\/\/wordpress.org\/plugins\/wp-json\/wporg\/v1\/users\/maxhandmade"}],"wp:attachment":[{"href":"https:\/\/wordpress.org\/plugins\/wp-json\/wp\/v2\/media?parent=359893"}],"wp:term":[{"taxonomy":"plugin_section","embeddable":true,"href":"https:\/\/wordpress.org\/plugins\/wp-json\/wp\/v2\/plugin_section?post=359893"},{"taxonomy":"plugin_tags","embeddable":true,"href":"https:\/\/wordpress.org\/plugins\/wp-json\/wp\/v2\/plugin_tags?post=359893"},{"taxonomy":"plugin_category","embeddable":true,"href":"https:\/\/wordpress.org\/plugins\/wp-json\/wp\/v2\/plugin_category?post=359893"},{"taxonomy":"plugin_contributors","embeddable":true,"href":"https:\/\/wordpress.org\/plugins\/wp-json\/wp\/v2\/plugin_contributors?post=359893"},{"taxonomy":"plugin_business_model","embeddable":true,"href":"https:\/\/wordpress.org\/plugins\/wp-json\/wp\/v2\/plugin_business_model?post=359893"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}