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

# Calculate Pricing

> Calculate localized pricing without a product.

# Calculate Pricing

Convert an amount from the merchant's baseline currency to a target currency using Khaime's exchange rates. Useful for displaying localized prices before creating a charge.

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

<ParamField query="amount" type="integer" required>
  Amount in the merchant's baseline currency (smallest unit: cents, kobo, etc.).
</ParamField>

<ParamField query="target_currency" type="string">
  Target currency code (e.g., `NGN`, `EUR`). If omitted, auto-detected from the customer's IP address.
</ParamField>

<ParamField query="source_currency" type="string">
  Source currency to convert from. Defaults to the merchant's baseline currency.
</ParamField>

<ParamField query="product_id" type="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.
</ParamField>

<ParamField query="customer_country" type="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.
</ParamField>

<ParamField query="sub_merchant_id" type="integer">
  For marketplace integrations. When provided, pricing uses the sub-merchant's baseline currency instead of the marketplace's.
</ParamField>

## Response

```json theme={null}
{
  "success": true,
  "data": {
    "pricing": {
      "base": {
        "amount": 10000,
        "currency": "USD",
        "formatted": "$100.00"
      },
      "local": {
        "amount": 16675000,
        "currency": "NGN",
        "formatted": "₦166,750.00"
      },
      "conversion": {
        "rate": 1450.1,
        "source": "wise_api",
        "applied": true
      }
    },
    "price_discrimination": {
      "original_base_price": 10000,
      "discrimination_amount": 1500,
      "discrimination_percentage": 0.15,
      "adjusted_base_price": 11500,
      "country_triggered": "NG"
    },
    "customer": {
      "location": {
        "country": "Nigeria",
        "country_code": "NG",
        "detected_from": "ip_address"
      },
      "currency": {
        "code": "NGN",
        "detected": false,
        "override": true
      }
    }
  },
  "meta": {
    "timestamp": "2026-03-28T14:00:00.000Z",
    "request_id": "req_1711630800000",
    "version": "v1",
    "mode": "sandbox"
  }
}
```

### Response Fields

| Field                                            | Type           | Description                                                        |
| ------------------------------------------------ | -------------- | ------------------------------------------------------------------ |
| `pricing.base`                                   | object         | Original amount in merchant's baseline currency                    |
| `pricing.local`                                  | object         | Converted amount in the target currency (after any discrimination) |
| `pricing.local.formatted`                        | string         | Human-readable formatted price (e.g., `"₦166,750.00"`)             |
| `pricing.conversion.rate`                        | number         | Exchange rate applied                                              |
| `pricing.conversion.source`                      | string         | Rate source: `wise_api`, `custom`, `api`, or `none`                |
| `pricing.conversion.applied`                     | boolean        | `true` if conversion was applied                                   |
| `price_discrimination`                           | object \| null | Discrimination breakdown if a rule matched; `null` otherwise       |
| `price_discrimination.original_base_price`       | integer        | Amount before the adjustment                                       |
| `price_discrimination.discrimination_amount`     | integer        | Amount added or subtracted                                         |
| `price_discrimination.discrimination_percentage` | number         | Decimal percentage (e.g., `0.15` for +15%)                         |
| `price_discrimination.adjusted_base_price`       | integer        | Amount after discrimination, before conversion                     |
| `price_discrimination.country_triggered`         | string         | ISO-2 country code that matched the rule                           |
| `customer.location`                              | object         | Geo-detected location (present when `target_currency` is omitted)  |
| `customer.currency.detected`                     | boolean        | `true` if currency was auto-detected from IP                       |

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

<Note>
  `price_discrimination` is only included in the response when `product_id` is provided. Without a product, Khaime has no rule context to evaluate.
</Note>

<Note>
  When `target_currency` matches the merchant's baseline currency, `conversion.applied` is `false` and `pricing.base` equals `pricing.local`.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  # Basic conversion — no discrimination
  curl "https://api.khaime.com/api/v1/partner/pricing/calculate?amount=10000&target_currency=NGN" \
    -H "X-API-Key: pk_sandbox_your_key"

  # With product_id — discrimination applied if a rule exists for NG
  curl "https://api.khaime.com/api/v1/partner/pricing/calculate?amount=10000&target_currency=NGN&product_id=3046" \
    -H "X-API-Key: pk_sandbox_your_key"

  # USD is ambiguous — pass customer_country explicitly
  curl "https://api.khaime.com/api/v1/partner/pricing/calculate?amount=10000&target_currency=USD&product_id=3046&customer_country=NG" \
    -H "X-API-Key: pk_sandbox_your_key"

  # Auto-detect currency from customer IP
  curl "https://api.khaime.com/api/v1/partner/pricing/calculate?amount=10000" \
    -H "X-API-Key: pk_sandbox_your_key"
  ```
</RequestExample>