Balances & ledgers

Your team carries four balances — SMS units, a KES wallet, email credits and international SMS units — each backed by an append-only ledger you can audit over the API.

The four balances

What each balance pays for

Field	Type	Required	Description
sms_balance	units	No	Local SMS. One unit = one message part. Topped up by purchasing units; spent by every send, campaign, reminder and survey message.
wallet_balance	KES	No	Real money. Pays one-time and service fees: sender ID registration, shortcode deposits, USSD setup — anything that isn't a per-message unit. Top it up via M-Pesa.
email_balance	credits	No	Transactional/bulk email sends.
intl_balance	units	No	International SMS routes.

Why the wallet matters

Most integration blockers we see are wallet-related: a sender ID or shortcode application sails through review, then stalls because the wallet can't cover the registration fee. If you have applications in flight, keep the wallet funded.

Check balances

GET/api/v1/units/balance

curl "https://api.mobilesasa.com/api/v1/units/balance" \
  -H "Authorization: Bearer $MOBILESASA_TOKEN"

Response — 200

{
  "success": true,
  "data": {
    "sms_balance": 15200,
    "wallet_balance": 3450.00,
    "email_balance": 0,
    "intl_balance": 0,
    "local_account_no": "MBS1234",
    "recent": [
      {
        "uuid": "a91f…",
        "entry_type": "usage",
        "units": -418,
        "balance_after": 15200,
        "description": "Campaign: July offer — Nairobi customers",
        "created_at": "2026-07-11T10:06:20Z"
      }
    ]
  }
}

local_account_no is your team's paybill account reference — you'll need it for manual M-Pesa deposits (see Top up via M-Pesa).

Legacy balance endpoint

If you only need the SMS balance and already use the frozen v1 API, GET /v1/get-balance/ works with your legacy token too.

SMS unit ledger

GET/api/v1/units/ledger

Every unit movement, append-only: purchases (credit), sends (usage), campaign reservations (reservation) and their releases (release). The running balance_after lets you reconcile to the current balance exactly.

curl "https://api.mobilesasa.com/api/v1/units/ledger?page=1&page_size=30" \
  -H "Authorization: Bearer $MOBILESASA_TOKEN"

Wallet ledger

GET/api/v1/units/wallet/ledger

KES movements: M-Pesa deposits (credit, with the mpesa_receipt number) and fee deductions (debit — sender ID registrations, shortcode deposits and similar, each with a human-readable description).

curl "https://api.mobilesasa.com/api/v1/units/wallet/ledger?page=1&page_size=30" \
  -H "Authorization: Bearer $MOBILESASA_TOKEN"

Response — 200

{
  "success": true,
  "data": [
    {
      "uuid": "f302…",
      "entry_type": "credit",
      "amount": 5000.00,
      "description": "M-Pesa deposit",
      "mpesa_receipt": "SGH8KL2M9Q",
      "created_at": "2026-07-10T14:03:51Z"
    },
    {
      "uuid": "0b7d…",
      "entry_type": "debit",
      "amount": -1550.00,
      "description": "Sender ID registration: DUKAPAY (safaricom)",
      "created_at": "2026-07-11T09:41:02Z"
    }
  ],
  "meta": { "page": 1, "page_size": 30, "total": 2 }
}