Skip to main content
GET

​
Intro

Converts an amount from the merchant’s baseline currency to a target currency using Khaime’s exchange rates — useful for showing a localized price, or computing the amount for Create Charge, before a product or cart total is involved.

​
Context

This is the generic, product-agnostic sibling of Get Product Pricing: use this when you already know an amount (e.g. a cart total from your own platform); use Get Product Pricing when the amount lives in a Khaime catalog product. Its local.amount is exactly the value Create Charge expects in its amount field when total_currency differs from currency — see the multicurrency workflow.

​
Hows

If target_currency is not provided, Khaime auto-detects the customer’s currency from their IP address. If product_id is provided, any active price discrimination rule for the customer’s country is applied to the amount before currency conversion.

​
Query parameters

​
integer
required
Amount in the merchant’s baseline currency (smallest unit: cents, kobo, etc.).
​
string
Target currency code (e.g., NGN, EUR). If omitted, auto-detected from the customer’s IP address.
​
string
Source currency to convert from. Defaults to the merchant’s baseline currency.
​
integer
Optional. When provided, Khaime looks up any active price discrimination rule for the product and applies it before converting. The customer’s country is derived from target_currency (e.g., NGN → NG) unless customer_country is explicitly set.
​
string
Override for the customer’s country used in rule lookup. 2-letter ISO code (e.g., NG). Only needed when target_currency is ambiguous (e.g., USD is used in many countries) and you know the customer’s exact location.
​
integer
For marketplace integrations. When provided, pricing uses the sub-merchant’s baseline currency instead of the marketplace’s.

​
Response

Response fields

​
How country is determined

When product_id is provided, Khaime resolves the customer’s country in this order:
  1. Explicit customer_country query parameter
  2. Country mapped from target_currency (e.g., NGN → NG, GHS → GH)
  3. IP geolocation fallback
For unambiguous currencies (NGN, GHS, KES, etc.) you don’t need to pass customer_country — the currency alone is sufficient.
price_discrimination is only included in the response when product_id is provided. Without a product, Khaime has no rule context to evaluate.
When target_currency matches the merchant’s baseline currency, conversion.applied is false and pricing.base equals pricing.local.

​
Whys

source_currency defaults to the merchant’s baseline currency rather than requiring it every call, since that’s the correct source in the overwhelming majority of requests — merchants price in one currency and this endpoint exists to localize that price outward. sub_merchant_id overrides the source currency to the sub-merchant’s baseline (not the marketplace operator’s) because in a marketplace, it’s the sub-merchant’s price that’s being localized, even though the request is authenticated as the operator.

​
Why nots

  • This endpoint does not create a charge or lock in the exchange rate for later use — it’s a live quote. Rates can drift between this call and a subsequent Create Charge request within the tolerance described there.
  • Without product_id, no price discrimination rule is evaluated — price_discrimination will always be null, even if a rule exists for that product elsewhere in the catalog.
  • customer_country only affects discrimination-rule lookup, not currency conversion itself — it does not override target_currency.