Billing Logic
This page explains exactly how AfriRoute turns your API calls into charges: when you are billed, what counts as a billable unit, how multi-segment and multi-recipient sends are rated, and how failures are handled. Understanding this prevents surprises and lets you forecast spend accurately.
The Billing Lifecycle
submit → reserve estimated cost → deliver → settle charge
↘ fail → release reservation (no charge)
- Submit — you call an API endpoint (e.g.
POST /v1/sms/send). - Reserve — AfriRoute reserves the estimated cost against your wallet so you cannot oversend.
- Deliver — the carrier confirms delivery.
- Settle — the reservation converts to a final charge in your ledger.
If the message fails or is rejected, the reservation is released and you are not charged.
Billable Units
| Product | Billable Unit | Billing Trigger |
|---|---|---|
| SMS | Per segment, per recipient | On delivery confirmation |
| Voice | Per minute (60s rounding) | On call completion |
| Per 24-hour conversation | On conversation open | |
| Mobile money payment | % of transaction value | On successful payment |
| Payout | % of transaction value | On successful disbursement |
| Number lookup | Per lookup | On API response |
SMS Billing Detail
SMS cost = segments × per-segment rate × recipients, after volume discount.
# 3 recipients, 200-char GSM-7 message (2 segments), Kenya at $0.0120
segments = 2
rate = 0.0120
recipients = 3
list_cost = segments * rate * recipients # 0.072
discounted = list_cost * 0.92 # Growth tier -8% => 0.06624
A bulk send is billed per recipient — sending to 5,000 numbers settles 5,000 individual charges, each conditional on that recipient's delivery.
What Is and Isn't Billed
| Event | Billed? |
|---|---|
| Message delivered | ✅ Yes |
| Message failed at carrier | ❌ No |
| Message rejected (policy/sender ID) | ❌ No |
| Invalid number (validation failure) | ❌ No |
| Message sent but DLR never returned within 48h | ✅ Yes (assumed delivered per carrier) |
| Inbound reply to your number | ✅ Yes (inbound rate) |
Discount Application
Volume discounts are computed on rolling 30-day delivered volume and applied at settlement. As your monthly volume crosses a tier boundary, subsequent messages settle at the lower effective rate automatically — there is no need to upgrade a plan.
Payments and Payouts
Payment processing and payout fees are deducted from the transaction, not your wallet:
Customer pays 1,000 KES via M-Pesa
→ AfriRoute fee 2.5% = 25 KES
→ You receive 975 KES settled to your balance
Payout example:
You disburse 1,000 KES to a driver
→ AfriRoute payout fee 1.5% = 15 KES
→ 1,015 KES total deducted from your balance
Idempotency and Double-Billing Protection
Pass an Idempotency-Key header on write requests. Retrying with the same key returns the original result without creating a second charge:
curl -X POST https://api.afriroute.ai/api/v1/sms/send \
-H "Authorization: Bearer $AFRIROUTE_API_KEY" \
-H "Idempotency-Key: order-12345-otp" \
-d '{ "to": "+254712345678", "from": "MyBrand", "message": "OTP 123456" }'
Reconciliation
Pull settled charges for any window to reconcile against your own records:
curl "https://api.afriroute.ai/api/v1/billing/usage?start=2026-05-01&end=2026-05-31&group_by=product" \
-H "Authorization: Bearer $AFRIROUTE_API_KEY"
Related
Billing questions? [email protected]
Last Updated: May 2026