Gatemi Currency Switcher Developer Reference

The two editions are separate code bases with separate prefixes: gmcswf_ for the free edition, gatemi_csw_ for the full edition. What they share is the two block names and the [gatemi_currency_switcher] shortcode, and the full edition copies the free edition's currencies (gmcswf_settings) into gatemi_csw_options the first time it loads with none of its own (marker gatemi_csw_free_migrated), then each currency's gateway list into gatemi_csw_checkout_options and — only when every carried currency has charm pricing on and no rounding increment — a .99 rule in every range of gatemi_csw_price_adjustment_settings, each written only while that option is still empty (marker gatemi_csw_free_migrated_extras).

Free edition

Storage

What Name Notes
Settings option gmcswf_settings currencies (list of rows), geoip (yes/no), sticky ('', left, right)
Currency row — code, rate (float, 6 decimals), auto (yes/no), decimals ('' or 0–4), position ('', left, right, left_space, right_space), rounding ('', 0.05, 0.10, 0.50, 1), charm (yes/no), gateways (list of gateway ids)
Cookie gmcswf_currency The shopper's currency code. 30 days, HttpOnly, path /.
Query argument gmcuf ?gmcuf=EUR switches currency. No nonce: it changes a display preference only.
Cron gmcswf_update_rates Twice daily, scheduled only while at least one currency is automatic.

The free edition caps currencies at three rows (GMCSWF_Currencies::SLOTS).

Filters

gmcswf_convert_fee

Whether one cart fee is in the base currency and should be converted. Return false for a fee your plugin already adds in the shopper's currency (for example a percentage of the converted cart).

Argument
$convert bool true
$fee object The cart fee

gmcswf_should_convert_coupon_amount

Return false to keep one coupon's amount unconverted.

Argument
$convert bool true
$amount mixed Stored amount, in the base currency
$coupon WC_Coupon The coupon

gmcswf_rates_api_url

The primary exchange-rate endpoint.

Argument
$url string https://gatemi.com/api/v1/exchange-rate.php
$base string Base currency code
$target string Target currency code

The plugin appends based_currency and target_currency and expects JSON with based_currency, target_currency and a positive exchange_rate.

gmcswf_rates_fallback_url

The fallback endpoint, called once for all pending currencies.

Argument
$url string https://open.er-api.com/v6/latest/{BASE}
$base string Base currency code

Expected JSON: result = success and a rates object.

// Use your own rate service for the primary lookup.
add_filter( 'gmcswf_rates_api_url', function ( $url, $base, $target ) {
	return 'https://rates.example.com/pair';
}, 10, 3 );

gmcswf_flag_url

The address of a currency's flag image.

Argument
$url string The bundled SVG
$flag string Two-letter flag code (eu for EUR)
$currency string Currency code

gmcswf_compatibility_modules

The ordered list of compatibility module class names booted on plugins_loaded. Remove one to switch it off.

Order meta

Written on woocommerce_checkout_create_order, woocommerce_store_api_checkout_order_processed and woocommerce_new_order:

Key Value
_gmcswf_fx_rate The rate the order was converted at (1 for a base-currency order)
_gmcswf_order_currency The order's currency
_gmcswf_base_currency Your base currency
_gmcswf_base_total Order total ÷ rate
_gmcswf_base_tax_total Tax total ÷ rate
_gmcswf_base_shipping_total Shipping total ÷ rate
_gmcswf_base_net_total (Total − tax − shipping) ÷ rate
$order    = wc_get_order( $order_id );
$in_base  = (float) $order->get_meta( '_gmcswf_base_total' );
$currency = $order->get_meta( '_gmcswf_base_currency' );

Shortcode and blocks

  • [gatemi_currency_switcher] — the switcher list.
  • Block gatemi-currency-switcher/switcher — the same list.
  • Block gatemi-currency-switcher/sticky-bar — the floating bar; pins right when the Sticky switcher bar setting is Off.

Both blocks are dynamic and server-rendered.

CSS classes

Class Element
.gmcswf-switcher The <ul> list
.gmcswf-item Each <li>
.gmcswf-current The shopper's current currency
.gmcswf-flag The flag <img> (18 × 12)
.gmcswf-sticky, .gmcswf-sticky-left, .gmcswf-sticky-right The sticky bar

The sticky bar's styles are an inline stylesheet registered as gmcswf-sticky, only printed when the bar is shown.

Caches

The plugin adds gmcswf_currency to WP Rocket's dynamic and mandatory cookies and to LiteSpeed Cache's vary cookies, so those caches keep one copy per currency. A request carrying ?gmcuf= defines DONOTCACHEPAGE and sends no-cache headers.

Uninstall

Removes gmcswf_settings, gmcswf_dhlexpress_currency, the cron event, and the per-currency Name Your Price bounds stored as product meta by the compatibility module. Order meta is kept.

Full edition

Storage

What Name
Currencies gatemi_csw_options — list of code, rate, rate_type (Auto/fixed), fee, fee_type (fixed/percentage), currency_pos, thousand_sep, decimal_sep, num_decimals
Checkout gatemi_csw_checkout_diff_currency, gatemi_csw_checkout_options
Display gatemi_csw_product_page_enable, gatemi_csw_switcher_position, gatemi_csw_sidebar_design, gatemi_csw_sidebar_pages, gatemi_csw_sidebar_position, gatemi_csw_design2_default_color, gatemi_csw_design2_active_color, gatemi_csw_menu_pages, gatemi_csw_enable_geolocation
Price rules gatemi_csw_price_adjustment_settings — enable, rounding, charm, test, one entry per range
Rates gatemi_csw_rates_last_updated
Licence gatemi_csw_license
Cookies gatemi_csw_currency (choice), gatemi_csw_currency_geo (location guess)
Cron gatemi_csw_update_exchange_rates_cron (hourly), gatemi_csw_license_check
Admin page admin.php?page=gatemi_csw_settings

Order meta uses the same names as the free edition with the _gatemi_csw_ prefix: _gatemi_csw_fx_rate, _gatemi_csw_order_currency, _gatemi_csw_base_currency, _gatemi_csw_base_total, _gatemi_csw_base_tax_total, _gatemi_csw_base_shipping_total, _gatemi_csw_base_net_total.

Filters

Filter Arguments What it does
gatemi_csw_exchange_rate_api_url $url, $base, $target Primary rate endpoint.
gatemi_csw_exchange_rate_fallback_url $url, $base Fallback rate endpoint.
gatemi_csw_should_convert_coupon_amount $convert, $amount, $coupon Return false to keep one coupon's amount unconverted.
gatemi_csw_checkout_notice_message $message, $display, $store, $symbol The "You will be charged in …" notice when checkout is forced to the base currency.
gatemi_csw_should_bypass_page_cache $bypass, $helper Whether this request sends no-cache headers.
gatemi_csw_is_currency_sensitive_request $sensitive, $helper Whether this request's output depends on the currency.
gatemi_get_all_currencies $currencies The currency list with effective rates.
gatemi_csw_currency_flag_code $flag, $code The flag shown for a currency.
gatemi_csw_flag_url $url, $flag_code A flag's image address.
gatemi_csw_compatibility_modules $modules The compatibility modules to boot.
gatemi_csw_setting_cap $cap Capability for the settings screen (default manage_woocommerce). The old misspelt gatemi_csw_curency_setting_cap is still applied first, for stores that hooked it.
gatemi_csw_license_api_url, gatemi_csw_update_cache_ttl, gatemi_csw_update_retry_ttl, gatemi_csw_sync_cache_ttl Licensing and updates.
// Never convert gift-card coupons.
add_filter( 'gatemi_csw_should_convert_coupon_amount', function ( $convert, $amount, $coupon ) {
	return 0 === strpos( $coupon->get_code(), 'gift-' ) ? false : $convert;
}, 10, 3 );

// Only administrators may open the settings.
add_filter( 'gatemi_csw_setting_cap', fn() => 'manage_options' );

Shortcodes and blocks

  • [gatemicswcurrency-switcher] and [gatemicswcurrency-switcher-shortcode] — the currency dropdown.
  • [gatemi_csw_sticky_side_bar] — the sidebar switcher.
  • Blocks gatemi-currency-switcher/switcher and gatemi-currency-switcher/sticky-bar. A page holding one of them skips the automatic placements.

Uninstall

Deletes every gatemi_csw_* option, including the licence. Order meta is kept.

Shopping Cart
Scroll to Top