Skip to Content

Wallet, Billing & Usage Accounting

Understand prepaid unit deduction mechanics, segment-based billing math, insufficient balance handling, and programmatic wallet queries.

View Markdown (.md)

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:

  1. Number of Recipients: Total count of distinct normalized phone numbers.
  2. Segment Count: Determined by the character length and encoding scheme (GSM-7 vs. UCS-2).
  3. Destination Rate: Country-specific unit pricing (Ghana domestic vs. international roaming destinations).

Unit Billing Formula

total_billable_units = unique_recipients * calculated_segments * destination_rate

Practical Billing Scenarios

Use CaseRecipient CountCharacter CountEncodingSegment CountBillable Units
Simple Auth OTP1 recipient48 charactersGSM-71 segment1 unit
Order Receipt (Plain)1 recipient155 charactersGSM-71 segment1 unit
Order Receipt (+ Emoji 📦)1 recipient156 charactersUCS-23 segments3 units
Flash Sale Broadcast5,000 recipients140 charactersGSM-71 segment5,000 units
Long Marketing Notice10,000 recipients280 charactersGSM-72 segments20,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 as 0 on 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.


On this page