> ## 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.

# Multicurrency

> How the WooCommerce plugin handles currency conversion.

# 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 Type | Examples                          | Cache Duration |
| ------------- | --------------------------------- | -------------- |
| Stable        | USD, EUR, GBP, CAD, AUD, CHF, JPY | 60 minutes     |
| Volatile      | NGN, GHS, KES, ZAR, UGX, XOF      | 15 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](/plugins/woocommerce/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.