Check balance

GET /balance returns the remaining SMS credit, the per-segment unit price, and the projected number of SMS your current balance can buy.

Request

cURL

curl $BASE_URL/api/v1/lisoloo/sms-api/balance \
  -H "app-key: $LISOLOO_API_KEY"

Python

r = requests.get(
    "$BASE_URL/api/v1/lisoloo/sms-api/balance",
    headers={"app-key": os.environ["LISOLOO_API_KEY"]},
    timeout=10,
)
print(r.json())

JavaScript

const r = await fetch(
  "$BASE_URL/api/v1/lisoloo/sms-api/balance",
  { headers: { "app-key": process.env.LISOLOO_API_KEY } },
);
console.log(await r.json());

PHP

$ch = curl_init('$BASE_URL/api/v1/lisoloo/sms-api/balance');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ["app-key: $apiKey"],
]);
echo curl_exec($ch);

Response

{
  "status_code": 200,
  "data": {
    "balance":                 100.50,
    "sms_wallet_balance":       80.00,
    "postpaid_wallet_balance":  20.50,
    "currency":                "USD",
    "unit_price":               0.02,
    "available_sms":            5025
  }
}

Field	Description
balance	Combined credit across both wallets (sms_wallet_balance + postpaid_wallet_balance), in currency. Decimal.
sms_wallet_balance	Prepaid SMS wallet credit. Drawn down first on every /send. Returns 0 if no prepaid wallet exists.
postpaid_wallet_balance	Postpaid wallet credit. Used as fallback once the prepaid wallet is exhausted (subject to your postpaid agreement). Returns 0 if no postpaid wallet exists.
currency	Three-letter ISO 4217 code — your merchant’s settlement currency. Pulled from the primary wallet’s currency reference.
unit_price	Cost of one SMS segment in currency. Read from your customer tarification row. Falls back to 0.01 if no tarification is configured.
available_sms	floor(balance / unit_price) — the number of additional segments your combined balance can buy right now.

Dual-wallet model

Lisoloo charges every send against two wallets in order:

1. LISOLOO_SMS — the prepaid SMS wallet you top up from the dashboard. Consumed first.
2. LISOLOO_POST_PAID — the postpaid wallet, only present if your account has a postpaid agreement. Consumed when the prepaid wallet runs out.

The endpoint returns 400 if neither wallet exists on your organization. If only one wallet exists, the other reports 0 and the balance reflects only the existing one.

Pre-flight cost estimation

Combine GET /balance with the segment counter from Character limits to refuse a send before submitting:

def can_afford(message: str, recipients: int) -> bool:
    bal      = requests.get(BALANCE_URL, headers=HEADERS).json()["data"]
    segments = count_segments(message)            # see /concepts/character-limits/
    cost     = segments * recipients * bal["unit_price"]
    return cost <= bal["balance"]

if not can_afford(MESSAGE, len(RECIPIENTS)):
    raise BalanceExhausted("Top up before sending.")

The gateway also enforces this server-side and returns 1202 INSUFFICIENT_BALANCE if you submit beyond your balance — but checking client-side avoids a wasted round-trip.

Caching

The balance endpoint is rate-limited to 30/min per key. Cache the response for ≥30 seconds in your application — balances don’t change faster than your own POST /send cadence, plus admin top-ups.

See also

• Calculate amount ↔ SMS — server-side two-way pricing calculator
• Character limits — segment counting
• Errors — 1202 INSUFFICIENT_BALANCE handling