# Wallet, Billing & Usage Accounting
URL: /docs/guides/wallet-and-billing

> 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 [#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 [#unit-billing-formula]

```text
total_billable_units = unique_recipients * calculated_segments * destination_rate
```

### Practical Billing Scenarios [#practical-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 [#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.

```http
GET /api/v1/public/sms/balance HTTP/1.1
Host: api.smspro.com
X-Api-Key: sk_live_example
```

```json
{
  "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`) [#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**:

```json
{
  "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 [#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 [#4-wallet-top-up-methods]

Add credit from the [SMS Pro console](https://smspro.com):

- **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.

---

## Related Documentation [#related-documentation]
- 📖 [SMS Fundamentals & Encoding](/docs/guides/sms-fundamentals)
- 📖 [Error Handling & Diagnostics](/docs/guides/error-handling-and-troubleshooting)
- 🔌 [API Reference: Get Account Balance](/docs/api-reference/authentication-balance/getBalance)