Developer overview and PHP functions

WC Currency Switch includes a small PHP API for themes, child themes and other plugins. Use it when you print a price that WooCommerce does not know about, such as a price stored in a custom field, or when your code needs to know which currency the visitor is shopping in. For example, a theme can show “Free delivery over 50 USD” as “Free delivery over 15.450 KWD” for a visitor from Kuwait.

How it works#

The plugin decides the visitor’s currency once per request, early in WordPress’s init action (priority 2). In order, it uses: the currency cookie, a language rule (Polylang or TranslatePress), geo detection on a first visit, and finally the default currency. When WPML with WooCommerce Multilingual is active, WooCommerce Multilingual’s currency comes first. In the WordPress admin it always uses the store currency.

The functions below read that decision and run amounts through the same conversion as product prices: the exchange rate (or the currency’s fixed rate), then the conversion fee, then rounding.

The functions are defined only when WooCommerce is active, during plugins_loaded. Guard calls in code that may run without the plugin:

if ( function_exists( 'wccs_active_currency' ) ) {
    $currency = wccs_active_currency();
}

PHP functions#

Function	Returns
wccs_active_currency(): string	The visitor’s currency code, for example KWD.
wccs_base_currency(): string	The store currency code (the WooCommerce currency, also called the base currency).
wccs_is_base_currency(): bool	true when the visitor is shopping in the store currency.
wccs_enabled_currencies(): array	Enabled currency codes in switcher order. Passes through the wccs_enabled_currencies filter.
wccs_rates(): array	Exchange rates against USD: units of each currency per 1 USD, whatever your store currency is. For a cross rate, divide two entries.
wccs_convert( float $price, ?string $to = null ): float	A store-currency amount converted to $to (default: the visitor’s currency), with rate, fee and rounding. Passes through the wccs_convert filter.
wccs_price( float $price, ?string $to = null ): string	The same amount as WooCommerce price HTML, in the target currency’s symbol, decimals, separators and symbol position.
wccs_switch_currency( string $currency ): bool	Switches the visitor’s currency for this request and writes the cookie. Returns false if the code is not enabled.
wccs_switch_url( string $currency, ?string $url = null ): string	A URL with ?wccs_cur=CODE added. Opening it switches the visitor to that currency. Defaults to the current page URL.
wccs_switcher_html( array $atts = [] ): string	The switcher HTML. Takes the same attributes as [wccs_switcher]. Passes through the wccs_switcher_html filter.

The API class#

Each function is also a static method on \NahnuMedia\WcCurrencySwitch\API, for example API::active_currency() or API::convert( 29.99, 'EUR' ). The class has two extra methods:

• API::currency_format( ?string $currency = null ): array returns a currency’s settings from the Pricing tab: decimals, decimal_sep, thousand_sep, symbol_pos, custom_symbol, fee_percent, rounding_type, rounding_target and fixed_rate. It defaults to the visitor’s currency.
• API::is_ready(): bool returns true once the plugin has started.

When to call them#

• Reading the currency: call wccs_active_currency() on init priority 3 or later, for example in wp, template_redirect or a template file. Before priority 2 the visitor’s currency is not decided yet and you get the default currency.
• Switching the currency: call wccs_switch_currency() on init at the default priority (10) or earlier, before any output. The plugin sets up its price conversion at init priority 15 for the currency chosen by then.
• On cart and checkout pages with Settle orders in base currency turned on, the plugin uses the store currency there, so wccs_active_currency() returns the store currency on those pages.

Examples#

Show a custom field price in the visitor’s currency. With a USD store, a KWD rate of 0.309 and no fee or rounding, a 10 USD field becomes 10 x 0.309 = 3.090 KWD:

$base = (float) get_post_meta( get_the_ID(), '_my_price', true );
echo wccs_price( $base ); // 3.090 with the KWD symbol for a KWD visitor

Prices printed with wccs_price() on a normal front-end page are also stored for every enabled currency, so they follow the visitor’s currency on a cached page like product prices do.

Show the same amount in a fixed currency, whatever the visitor uses:

echo wccs_price( 50.0, 'EUR' );

Switch logged-in wholesale customers to GBP:

add_action( 'init', function () {
    if ( function_exists( 'wccs_switch_currency' ) && current_user_can( 'wholesale_customer' ) ) {
        wccs_switch_currency( 'GBP' );
    }
} );

Here wholesale_customer is an example capability: use the one your site has.

Good to know#

• wccs_switch_url() is meant for links in emails, ads and landing pages. On your own pages, use [wccs_switcher] or the JavaScript API, which switch without changing the URL.
• wccs_rates() returns the raw provider rates. It does not include fixed rates, fees or rounding. Use wccs_convert() for shopper prices.
• The wccs_convert filter changes the result of wccs_convert() and wccs_price() only. Normal product prices do not pass through it.

Related docs#

• Filters and actions
• The currency cookie and price data
• JavaScript API
• How converted prices are worked out