Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.khaime.com/llms.txt

Use this file to discover all available pages before exploring further.

​
WooCommerce Multicurrency

The plugin converts all WooCommerce prices to the customer’s selected currency in real-time.

​
How It Works

  1. Currency detection: Customer’s currency is detected by IP geolocation on first visit
  2. Price conversion: All product prices, shipping, and totals are converted using live exchange rates
  3. Currency switcher: Floating widget lets customers manually change currency
  4. Checkout: Payment is processed in the customer’s currency via the appropriate gateway

​
Currency Detection Priority

The plugin determines the customer’s currency using this priority:
  1. Currency switcher selection — if the customer has manually chosen a currency
  2. WooCommerce session — persisted from a previous page in the same session
  3. IP geolocation — automatically detected via the Khaime API on first visit
  4. Baseline currency — your store’s default currency (fallback)

​
Exchange Rates

​
Rate Sources

The plugin uses the Khaime pricing API as the primary rate source. This ensures display prices match exactly what the customer will be charged — including any fees or markup configured in your Khaime dashboard. If the pricing API is unavailable, the plugin falls back to the Khaime localization API for raw exchange rates.

​
Caching

Rates are cached with volatility-aware durations to balance accuracy and performance:
Currency TypeExamplesCache Duration
StableUSD, EUR, GBP, CAD, AUD, CHF, JPY60 minutes
VolatileNGN, GHS, KES, ZAR, UGX, XOF15 minutes
You can flush all cached rates from the Diagnostics section of the settings page.

​
What Gets Converted

  • Product prices (regular, sale, and variation prices)
  • Cart item prices and subtotals
  • Shipping rates
  • Order totals
  • Currency symbols
  • Mini-cart totals
  • WAPF / Product Add-Ons pricing labels
All conversions happen at display time — original prices in the database are never modified.

​
Page Caching Compatibility

The plugin is designed to work with full-page caching (Varnish, WP Super Cache, etc.):
  • On cacheable pages (shop, product listings, home), prices are converted client-side via JavaScript after page load. This means CDN and page caches can serve a single cached version to all visitors.
  • On transactional pages (cart, checkout, my-account), prices are converted server-side so WooCommerce’s totals engine calculates correctly.
This hybrid approach gives you the best of both worlds — fast cached pages and accurate checkout totals.

​
Third-Party Plugin Compatibility

​
WAPF (WooCommerce Advanced Product Fields)

The plugin fully supports WAPF addon pricing:
  • Addon prices (e.g. ”+$500.00 for Clothing”) are converted to the customer’s currency
  • Cart labels showing addon prices are re-formatted at display time
  • The checkout total includes all converted addon amounts

​
Page Builders & Custom Themes

If your theme renders prices using non-standard markup, use the Custom Price Selectors setting to tell the converter where to find them. See Configuration → Custom Price Selectors.

​
Currency Switching

When a customer selects a new currency from the switcher:
  1. The selection is saved as a cookie (30-day expiry)
  2. The page reloads to ensure all components update consistently
  3. Mini-cart fragments are refreshed with the new currency

​
Currency Switcher Widget

​
Floating Switcher (Auto-injected)

Appears in the bottom-right corner on configured pages. Shows country flags and currency codes. Automatically inherits your theme’s accent color.

​
Shortcode

[khaime_currency_switcher]
[khaime_currency_switcher style="buttons"]

​
Widget

Add via Appearance → Widgets → Khaime Currency Switcher. Supports dropdown or button style.

​
Supported Currencies

USD, EUR, GBP, NGN, GHS, KES, ZAR, CAD, AUD, NZD, CHF, JPY, SEK, DKK, NOK, PLN, INR, BRL, MXN, SGD, HKD, RWF, TZS, UGX, XOF, XAF

​
Error Handling

If the exchange rate API is unavailable when a customer tries to switch currency:
  • The currency switch is blocked rather than showing prices with a wrong symbol
  • The switcher reverts to the previous currency
  • Errors are logged to WooCommerce → Status → Logs
This prevents customers from seeing incorrect prices (e.g. showing a ₦ symbol with USD amounts).

​
Troubleshooting

​
Prices not converting

  • Check the API connection: KhaimePay Settings → Test Connection
  • Flush caches: KhaimePay Settings → Flush All Caches
  • Check WooCommerce logs: WooCommerce → Status → Logs → khaimepay

​
Prices showing very large numbers

  • Usually indicates double conversion. Flush all caches from the KhaimePay settings page and clear your browser cookies.
  • Ensure your baseline currency matches your Khaime dashboard setting.

​
Mini-cart showing wrong currency symbol

  • The mini-cart uses WooCommerce cart fragments that may be cached in the browser. Switching currency triggers a page reload which refreshes the fragments. If it persists, use Flush All Caches in KhaimePay settings and clear your browser cache.