Wallet, Billing & Usage Accounting
Understand prepaid unit deduction mechanics, segment-based billing math, insufficient balance handling, and programmatic wallet queries.
SMS Pro operates on a transparent Prepaid Wallet & Credit Allocation model. Billing is strictly correlated to the telecommunication infrastructure resources consumed by your messages.
1. How SMS Billing Is Calculated
The cost of any outbound SMS transmission is determined by three variables:
- Number of Recipients: Total count of distinct normalized phone numbers.
- Segment Count: Determined by the character length and encoding scheme (GSM-7 vs. UCS-2).
- Destination Rate: Country-specific unit pricing (Ghana domestic vs. international roaming destinations).
Unit Billing Formula
total_billable_units = unique_recipients * calculated_segments * destination_ratePractical Billing Scenarios
| Use Case | Recipient Count | Character Count | Encoding | Segment Count | Billable Units |
|---|---|---|---|---|---|
| Simple Auth OTP | 1 recipient | 48 characters | GSM-7 | 1 segment | 1 unit |
| Order Receipt (Plain) | 1 recipient | 155 characters | GSM-7 | 1 segment | 1 unit |
| Order Receipt (+ Emoji 📦) | 1 recipient | 156 characters | UCS-2 | 3 segments | 3 units |
| Flash Sale Broadcast | 5,000 recipients | 140 characters | GSM-7 | 1 segment | 5,000 units |
| Long Marketing Notice | 10,000 recipients | 280 characters | GSM-7 | 2 segments | 20,000 units |
2. Programmatic Wallet Balance Queries
Call GET /api/v1/public/sms/balance. The same payload is available from POST /api/v1/public/sms/balance. The response is the account balance. A test key does not return a separate sandbox balance.
GET /api/v1/public/sms/balance HTTP/1.1
Host: api.smspro.com
X-Api-Key: sk_live_example{
"status": "success",
"message": null,
"data": {
"paygBalance": 0,
"bundleRemaining": 2400,
"unit": "SMS"
}
}paygBalance: Returned as0on this endpoint.bundleRemaining: The account SMS credit balance.unit:SMS.
3. Handling Insufficient Balance (HTTP 402)
If your wallet lacks the credits required to service an API dispatch, the gateway rejects the entire request atomically:
{
"type": "https://docs.smspro.com/errors/insufficient-credits",
"title": "INSUFFICIENT CREDITS",
"status": 402,
"detail": "Insufficient credits for this send.",
"instance": "/api/v1/public/sms/send",
"code": "INSUFFICIENT_CREDITS",
"message": "Insufficient credits for this send.",
"requestId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
}Architectural Guarantees
- Atomic Rejection: In batch requests, SMS Pro never performs partial sends if balance is insufficient. The entire request fails so your application does not end up in an inconsistent state.
- Zero Debt: Accounts cannot run into negative balances. Dispatches halt cleanly until a wallet top-up is processed.
4. Wallet Top-Up Methods
Add credit from the SMS Pro console:
- Top up at
/customer/wallet/top-up. - Buy a bundle at
/customer/wallet/buy-bundle. - History is at
/customer/wallet/history.
Account settings can send email and SMS alerts. Watch the wallet balance on the dashboard as well.