curl "https://api.khaime.com/api/v1/currencies?can_customer_pay=true"
Products & Pricing
Get Currencies
List every currency Khaime can price and charge in.
GET
/
currencies
curl "https://api.khaime.com/api/v1/currencies?can_customer_pay=true"
Intro
Returns the currencies Khaime currently supports, each with its symbol and a representative country. Use it to build a currency selector on your storefront, then pass the customer’s chosen code ascurrency when you fetch products.
This endpoint is public — no
X-API-Key is needed, so you can call it straight from the browser.Context
Get Currencies is the first step in Prices, Fees and Totals, the guide to showing customers the right price, fee and total at each step of checkout. Every code this returns is accepted as thecurrency parameter on Get Product and Get Product Pricing, which return the product’s price converted into that currency. The list is the live version of the table on Multicurrency — read it from here rather than hard-coding codes, so new currencies appear on your storefront without a release.
Hows
Query parameters
boolean
true returns only currencies customers can pay in. Use this for a storefront currency selector.boolean
true returns only currencies a business can settle in. This is a much shorter list, and is not what customers should choose from.boolean
default:"false"
true also returns currencies that are switched off. Leave it out for storefronts.Response
data is a flat array, sorted by currency_iso.
{
"status": true,
"success": true,
"message": "Currencies retrieved successfully",
"data": [
{
"currency_iso": "EUR",
"currency_symbol": "€",
"country_code": "DE",
"country_name": "Germany",
"is_active": true
},
{
"currency_iso": "GBP",
"currency_symbol": "£",
"country_code": "GB",
"country_name": "United Kingdom",
"is_active": true
},
{
"currency_iso": "NGN",
"currency_symbol": "₦",
"country_code": "NG",
"country_name": "Nigeria",
"is_active": true
}
]
}
| Field | Type | Description |
|---|---|---|
currency_iso | string | ISO 4217 code. Pass this as currency on product endpoints. |
currency_symbol | string | Display symbol, e.g. ₦. Several currencies share $, so show the code alongside it. |
country_code | string | ISO 3166-1 alpha-2 code of one country that uses the currency. Handy for a flag icon. |
country_name | string | Name of that country. |
is_active | boolean | Always true unless you pass include_inactive=true. |
Best practice: default to local currency
Show each customer prices in their own currency from the first page view, and let them change it.1
Load the currency list
Call
GET /currencies?can_customer_pay=true once and cache it — it changes rarely.2
Detect the customer's country from their IP
Most hosts give you this for free in a request header:
CF-IPCountry on Cloudflare, X-Vercel-IP-Country on Vercel, CloudFront-Viewer-Country on AWS CloudFront. Otherwise use any IP geolocation service.3
Map the country to a currency
Use your own country → currency map (France →
EUR, Senegal → XOF), then check the result is in the list. If the country is unknown or its currency isn’t supported, fall back to USD or your store’s base currency.4
Fetch prices in that currency
Pass the code as
currency on Get Product or Get Product Pricing.5
Let the customer change it
Put a currency selector somewhere visible, built from this list. When the customer picks one, save it (cookie or local storage) and use it on every later visit — a customer’s own choice always beats detection.
Storefront example
// 1. Supported currencies (cache this).
const { data: currencies } = await fetch(
"https://api.khaime.com/api/v1/currencies?can_customer_pay=true"
).then((r) => r.json());
const supported = new Set(currencies.map((c) => c.currency_iso));
// 2–3. Saved choice first, then the IP country, then a fallback.
const COUNTRY_CURRENCY = { NG: "NGN", GB: "GBP", FR: "EUR", DE: "EUR", US: "USD" /* … */ };
function pickCurrency(savedCurrency, ipCountry) {
if (supported.has(savedCurrency)) return savedCurrency;
const local = COUNTRY_CURRENCY[ipCountry];
return supported.has(local) ? local : "USD";
}
// 4. Price every product in that currency — from your server, with your API key.
const currency = pickCurrency(cookies.get("currency"), request.headers.get("cf-ipcountry"));
const product = await fetch(
`https://api.khaime.com/api/v1/product/${productId}?currency=${currency}`,
{ headers: { "X-API-Key": process.env.KHAIME_API_KEY } }
).then((r) => r.json());
curl "https://api.khaime.com/api/v1/currencies?can_customer_pay=true"
Whys
Defaulting to the customer’s local currency is what shoppers expect: they see a price they understand without doing anything, and there’s no foreign price or card conversion fee to put them off at checkout. Detection is only a guess, though — VPNs, travel and expats all break it — so the customer must be able to override it, and their choice must stick.Why nots
- One country per currency, not every country.
country_codenames a single country for each currency (EURlists Germany,XOFlists Côte d’Ivoire), so it can’t map a visitor’s country to a currency on its own — keep your own map. For a flag, many storefronts show the EU flag forEURrather than Germany’s. - Don’t rely on Khaime’s IP detection from your server. When you omit
currency, Get Product Pricing guesses from the IP of whoever called the API. If that’s your backend, it sees your server’s location, not the customer’s. Detect the country yourself and passcurrencyexplicitly. - Displaying a currency isn’t the same as charging in it. Charging in a currency other than the product’s base currency requires multicurrency to be enabled for the merchant; see Multicurrency.
- List Products doesn’t convert. It always returns each product’s base currency. Fetch converted prices per product with Get Product or Get Product Pricing.