Filters and actions

Hooks let your own code change what WC Currency Switch does, or react when something happens, without editing the plugin. A filter receives a value and returns it, changed or not. An action tells your code that something happened. For example, you can pick the currency from a custom language setup, load flag images from your own CDN, or clear an extra cache when exchange rates move.

Add hooks in a small custom plugin or in your child theme’s functions.php. Every hook name below was checked in the plugin’s code.

Filters#

Filter	Arguments	Use
wccs_language_currency	string $currency (starts as an empty string)	Return a currency code to use for the current page’s language. Runs on front-end requests.
wccs_skip_conversion_product_{$product_id}	bool $skip (true when the product has a fixed price in the current currency)	Return true to stop the plugin converting that product’s price.
wccs_convert	float $converted, float $original, string $from, string $to	Change the result of wccs_convert() and wccs_price(). Storefront product prices do not pass through it.
wccs_enabled_currencies	array $currencies	Change the list returned by wccs_enabled_currencies(). The switcher itself lists the currencies enabled in the settings.
wccs_switcher_html	string $html, array $atts	Change the HTML returned by wccs_switcher_html(). The [wccs_switcher] shortcode output does not pass through it.
wccs_flag_base_url	string $url	Load flag images from your own server or CDN.

Details#

• wccs_language_currency: the plugin uses your code only if it is an enabled currency and the visitor has no currency cookie. A cookie (the visitor’s own choice) always wins. When a language currency applies, the plugin also skips writing a geo-detected cookie on that page, so the language keeps deciding on later pages. Polylang and TranslatePress rules use this filter at priority 10 and do not overwrite a code that is already set, so add your callback below 10 to run first, or above 10 to see their result.
• wccs_skip_conversion_product_{$product_id}: for a variation, the ID is the variation’s ID. The price range of a variable product (“from 10 to 20”) is built separately and does not use this filter. Skipping leaves the stored number as it is but the shopper’s currency symbol is still shown, so only return true when your own code has already put the price in the shopper’s currency.
• wccs_flag_base_url: the default is the plugin’s assets/flags/ folder. Your folder needs w20/ and w40/ subfolders with lower-case {country}.png files, for example w20/kw.png. The 40 px file is used when a flag is shown larger than 30 px.

Actions#

Action	Arguments	Fires when
wccs_currency_switched	string $new, string $old	The server writes the currency cookie.
wccs_rates_updated	array $rates, array $previous, string $source, string $provider	New exchange rates are stored.
wccs_rates_refreshed	array $rates, string $provider	Someone clicks Force Refresh on the Rate Provider tab.
wccs_page_cache_purged	array $caches	The plugin cleared page caches because a rate moved.

Details#

• wccs_currency_switched: fires for wccs_switch_currency(), a ?wccs_cur= link, geo detection on a first visit that PHP renders, and Change currency follow at checkout (billing or shipping country). It does not fire when a visitor picks a currency in the switcher or a nav menu, because the browser writes that cookie. Use the wccs:currency browser event for those (see JavaScript API). For a ?wccs_cur= link or a first visit, $old is the default currency, because the earlier currency is not known yet.
• wccs_rates_updated: $source is scheduled (the cached rates expired and were fetched again on the next request, see Rate Cache TTL) or manual (Force Refresh). $previous is empty on the very first fetch. It does not fire when a fetch fails.
• wccs_rates_refreshed: $rates is empty when the refresh failed; the previous rates stay in use.
• wccs_page_cache_purged: $caches lists the caches the plugin cleared, for example LiteSpeed or WP Rocket. It runs at the end of the request after a rate moved more than the threshold set on the Rate Provider tab.

Provider slugs are frankfurter, exchangerate, openexchange, currencyapi and custom.

Examples#

Euro for a French-language site in a custom multilingual setup:

add_filter( 'wccs_language_currency', function ( $currency ) {
    return str_starts_with( get_locale(), 'fr' ) ? 'EUR' : $currency;
}, 5 );

Clear a custom cache when the plugin clears page caches:

add_action( 'wccs_page_cache_purged', function ( array $caches ) {
    my_host_cache_flush(); // your host's or CDN's purge function
} );

Log when the euro rate moves by more than 2% (rates are per 1 USD):

add_action( 'wccs_rates_updated', function ( $rates, $previous, $source, $provider ) {
    if ( empty( $previous['EUR'] ) || empty( $rates['EUR'] ) ) {
        return;
    }
    $move = abs( $rates['EUR'] / $previous['EUR'] - 1 );
    if ( $move > 0.02 ) {
        error_log( sprintf( 'EUR moved %.1f%% (%s, %s)', $move * 100, $source, $provider ) );
    }
}, 10, 4 );

Related docs#

• Developer overview and PHP functions
• JavaScript API
• Clearing caches when exchange rates change
• Currency by language (Polylang and TranslatePress)