Calculate amount ↔ SMS count

POST /calculate is the two-way pricing calculator: pass an amount, get back how many SMS it buys; pass an SMS count, get back the amount needed to send them. It mirrors the in-dashboard widget so external callers don’t have to re-implement the average-price aggregation client-side.

The conversion uses the average price across every (country × telephone network × pricing) tuple configured on your merchant, in your wallet currency. If the merchant has no pricings configured the endpoint returns 400.

Amount → SMS count

Pass mode: "amount_to_sms" with a positive amount. The response includes the floor of amount / average_price — never more SMS than the amount actually buys.

curl $BASE_URL/api/v1/lisoloo/sms-api/calculate \
  -X POST \
  -H "app-key: $LISOLOO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "amount_to_sms",
    "amount": 10
  }'

r = requests.post(
    f"{API_URL}/calculate",
    headers=HEADERS,
    json={"mode": "amount_to_sms", "amount": 10},
    timeout=10,
)
r.raise_for_status()
data = r.json()["data"]
print(f"$10 buys {data['sms_count']} SMS at {data['average_price']} {data['currency']}/SMS")

const r = await fetch(`${API_URL}/calculate`, {
  method: "POST",
  headers: HEADERS,
  body: JSON.stringify({ mode: "amount_to_sms", amount: 10 }),
});
const { data } = await r.json();
console.log(`$10 buys ${data.sms_count} SMS at ${data.average_price} ${data.currency}/SMS`);

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL            => "$apiUrl/calculate",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        "app-key: $apiKey",
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        'mode'   => 'amount_to_sms',
        'amount' => 10,
    ]),
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
echo "{$result['data']['sms_count']} SMS";

SMS count → Amount

Pass mode: "sms_to_amount" with a positive sms_count. The response includes sms_count × average_price rounded to two decimals.

curl $BASE_URL/api/v1/lisoloo/sms-api/calculate \
  -X POST \
  -H "app-key: $LISOLOO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "sms_to_amount",
    "sms_count": 2000
  }'

r = requests.post(
    f"{API_URL}/calculate",
    headers=HEADERS,
    json={"mode": "sms_to_amount", "sms_count": 2000},
    timeout=10,
)
data = r.json()["data"]
print(f"2000 SMS costs {data['amount']} {data['currency']}")

const r = await fetch(`${API_URL}/calculate`, {
  method: "POST",
  headers: HEADERS,
  body: JSON.stringify({ mode: "sms_to_amount", sms_count: 2000 }),
});
const { data } = await r.json();
console.log(`2000 SMS costs ${data.amount} ${data.currency}`);

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL            => "$apiUrl/calculate",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        "app-key: $apiKey",
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        'mode'      => 'sms_to_amount',
        'sms_count' => 2000,
    ]),
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $result['data']['amount'] . ' ' . $result['data']['currency'];

Response

{
  "status_code": 200,
  "data": {
    "mode": "amount_to_sms",
    "amount": 10.00,
    "sms_count": 500,
    "average_price": 0.0200,
    "currency": "USD",
    "currency_symbol": "$"
  }
}

Field	Description
`mode`	Echoed back from the request.
`amount`	Wallet amount. Input value when `mode='amount_to_sms'`; computed (rounded to 2 decimals) when `mode='sms_to_amount'`.
`sms_count`	SMS count. Computed (floored, never above what the amount buys) when `mode='amount_to_sms'`; input value when `mode='sms_to_amount'`.
`average_price`	Per-SMS price used for the conversion, in `currency`, rounded to 4 decimals.
`currency`	Three-letter ISO 4217 code — your wallet currency.
`currency_symbol`	Display symbol for `currency` (e.g. `$`, `€`, `FC`).

Request fields

Field	Type	Required	Description
`mode`	enum	Yes	`amount_to_sms` or `sms_to_amount`.
`amount`	float	When `mode='amount_to_sms'`	`0 ≤ amount ≤ 10 000 000`.
`sms_count`	int	When `mode='sms_to_amount'`	`0 ≤ sms_count ≤ 10 000 000`.

0 is accepted as input — the response will simply contain 0 for the computed field too, matching how the dashboard widget clears its result.

How the average price is computed

The gateway pulls every pricing row configured on your merchant — each row covers one (country, telephone network) tuple — and averages them arithmetically in the wallet currency. There is no weighting by traffic volume; every configured destination contributes equally.

This makes the calculator a planning tool, not a per-message guarantee: an actual POST /send charges the exact pricing of each destination’s network, which may differ from the average reported here.

What can go wrong

HTTP	Cause	Fix
`400` — `"'amount' is required when mode='amount_to_sms'"`	`mode='amount_to_sms'` but no `amount`.	Add `amount`.
`400` — `"'sms_count' is required when mode='sms_to_amount'"`	`mode='sms_to_amount'` but no `sms_count`.	Add `sms_count`.
`400` — `Invalid mode`	`mode` not in the enum.	Use `amount_to_sms` or `sms_to_amount` (lowercase).
`400` — no pricing	The merchant has no `(country × network × pricing)` rows configured.	Configure pricings in the dashboard or contact support.