Technical documentation / Ston Currency Switcher
Setup, a step-by-step tutorial for every screen, the shortcode and settings reference and how it stays cache-friendly — the complete documentation for Ston Currency Switcher.
01 / At a glance
Multi-currency that stays fast and never fights your cache.
No reload
Prices, cart totals and the mini cart update without a page reload, through a WooCommerce AJAX endpoint.
Cache friendly
Registers its cookie with WP Rocket and LiteSpeed Cache, and a geolocated first visit never becomes the shared cached page.
Light
No jQuery; one small deferred script and stylesheet, loaded only on pages with a switcher. Settings are read once per request — no query per price.
Modern Woo
Works with the block cart and checkout, High-Performance Order Storage and the Store API.
Control
Rate, extra fee, rounding rules and full formatting per currency — or a fixed price on any product or variation.
Private
Country comes from the Cloudflare header or the WooCommerce MaxMind database. Rates come from open.er-api.com, no key needed.
02 / Install
Plugins → Add New → Upload. WooCommerce 8.0+ must be active. A Ston Currency menu appears with Currencies, Switcher, Settings and Help.
WooCommerce → Settings → General sets your store currency. Every price stays managed in it; other currencies are converted from it.
03 / Tutorial / Currencies
Ston Currency → Currencies. Add, remove, enable, disable and drag to reorder.
Pick it from the list. The store currency is always there with rate 1.
Type it by hand, or turn on automatic rates in Settings to update them twice a day.
An extra percentage on top of the rate, to cover conversion costs.
None, nearest whole (179.95 → 180), round up, charm price (179.10 → 179.99), nearest 5 or nearest 10.
Symbol, symbol position (left, right, with or without a space), decimals, thousands and decimal separators.
List the countries that should see this currency first. Turn on “pick currency by visitor country” in Settings.
04 / Tutorial / Switcher
Ston Currency → Switcher sets the default look; every placement can override it.
Pills (segmented buttons), dropdown menu, native select box or inline text links.
Code (USD), symbol ($), code and symbol, name, or name and code — with optional flags.
Drag the Ston Currency widget; it has its own size and glass style controls.
anywhere, or the classic widget in a sidebar.
Append it to a theme menu location, or show a floating button bottom-left or bottom-right.
On every page, or on store pages only (shop, product, cart, checkout).
05 / Tutorial / Store
Settings: charge in the currency the customer selected, or always in the store currency if your payment gateway needs it.
On a product or variation, enter a fixed price per currency when a converted price is not good enough.
Fixed coupon amounts, minimum and maximum spend, shipping costs and the free-shipping minimum are converted automatically.
$49 shows any store-currency amount in the visitor’s currency — ideal for pricing tables.
06 / Shortcodes
Shows the switcher with the defaults from Ston Currency → Switcher.
style=”pills | dropdown | select | links”
Switcher type.
label=”code | symbol | code_symbol | name | name_code”
What each option shows.
flags=”yes”
Show country flags.
show=”all | store”
Every page, or store pages only.
class=”…”
Extra CSS class on the wrapper.
$49
Converts a store-currency amount to the visitor’s currency, formatted like a WooCommerce price.
07 / Settings reference
Default currency
The currency first-time visitors see (empty = store currency).
Geolocation
Pick the currency by visitor country on the first visit (off by default).
Switch without reload
Update prices in place via AJAX (on by default).
Trim zeros
Show 49 instead of 49.00 (on by default).
Checkout currency
Selected currency, or always the store currency.
Automatic rates
Update rates twice a day from open.er-api.com (off by default).
Delete data on uninstall
Off by default.
08 / Developer reference
ston_currency_current
filter — the currency in use for this request
ston_currency_converted_amount
filter — a converted amount before formatting
ston_currency_fetched_rates · ston_currency_rates_url
filters — the downloaded rates and their source
ston_currency_label · ston_currency_flag_country
filters — option label and flag
ston_currency_switcher_html
filter — the final switcher markup
ston_currency_is_store_page
filter — what counts as a store page
ston_currency_ajax_regions
filter — page regions refreshed after a switch
ston_currency_switched · ston_currency_options_updated
actions — after a switch, after settings are saved
Stored data
One options entry, one cookie for the chosen currency, and fixed prices as product meta.
09 / Troubleshooting
Prices do not change after switching
Make sure the page cache keeps a copy per currency (WP Rocket and LiteSpeed are configured automatically). Other caches need the currency cookie added.
The payment gateway rejects a currency
Set Checkout currency to “store currency”.
Wrong first currency
Check the default currency and the country list; geolocation needs Cloudflare or the WooCommerce MaxMind database.
Rates are old
Turn on automatic rates and make sure WP-Cron runs.
A section of the page keeps the old price
Add its selector with ston_currency_ajax_regions, or turn off switch-without-reload.