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

# Get Currencies

> List every currency Khaime can price and charge in.

## 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 as `currency` when you fetch products.

<Note>
  This endpoint is public — no `X-API-Key` is needed, so you can call it straight from the browser.
</Note>

## Context

Get Currencies is the first step in [Prices, Fees and Totals](/api-reference/pricing-and-checkout-guide), the guide to showing customers the right price, fee and total at each step of checkout.

Every code this returns is accepted as the `currency` parameter on [Get Product](/api-reference/commerce/get-product) and [Get Product Pricing](/api-reference/products/get-pricing), which return the product's price converted into that currency. The list is the live version of the table on [Multicurrency](/payments/multicurrency#supported-currencies) — read it from here rather than hard-coding codes, so new currencies appear on your storefront without a release.

## Hows

### Query parameters

<ParamField query="can_customer_pay" type="boolean">
  `true` returns only currencies customers can pay in. Use this for a storefront currency selector.
</ParamField>

<ParamField query="can_business_collect" type="boolean">
  `true` returns only currencies a business can settle in. This is a much shorter list, and is not what customers should choose from.
</ParamField>

<ParamField query="include_inactive" type="boolean" default="false">
  `true` also returns currencies that are switched off. Leave it out for storefronts.
</ParamField>

### Response

`data` is a flat array, sorted by `currency_iso`.

```json theme={null}
{
  "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.

<Steps>
  <Step title="Load the currency list">
    Call `GET /currencies?can_customer_pay=true` once and cache it — it changes rarely.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Fetch prices in that currency">
    Pass the code as `currency` on [Get Product](/api-reference/commerce/get-product) or [Get Product Pricing](/api-reference/products/get-pricing).
  </Step>

  <Step title="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.
  </Step>
</Steps>

```javascript Storefront example theme={null}
// 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());
```

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.khaime.com/api/v1/currencies?can_customer_pay=true"
  ```
</RequestExample>

## 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_code` names a single country for each currency (`EUR` lists Germany, `XOF` lists 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 for `EUR` rather than Germany's.
* **Don't rely on Khaime's IP detection from your server.** When you omit `currency`, [Get Product Pricing](/api-reference/products/get-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 pass `currency` explicitly.
* **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](/payments/multicurrency).
* **[List Products](/api-reference/products/list-products) doesn't convert.** It always returns each product's base currency. Fetch converted prices per product with [Get Product](/api-reference/commerce/get-product) or [Get Product Pricing](/api-reference/products/get-pricing).