Bulkit
Register

Get Account Balance

Retrieve the current credit balance available in your Bulkit wallet.

Last updated · Markdown version

This is useful for:

  • pre-flight credit checks before sending campaigns
  • monitoring available balance in dashboards and billing systems
  • alerting when your account balance is low

Endpoint title

Get Account Balance

What this endpoint does

Returns the real-time cash credit balance, active Smart Bundle credits, last updated timestamp, and wallet currency for the authenticated Bulkit client account.

HTTP method and path

HTTP
GET /api/v2/account/credits

Authorization requirements

This endpoint supports:

  • Bearer token (recommended): Authorization: Bearer <api_key>
  • Legacy headers: X-API-Key and X-API-Secret
  • URL query parameter: ?apikey=<api_key>

Bearer token authorization is preferred.

Endpoint code block

HTTP
GET https://api.bulkitsms.com/api/v2/account/credits

Authorization example

HTTP
Authorization: Bearer bk_live_8n6JQv3K1h9Lp0Md

Request examples

cURL / Bash
curl -X GET "https://api.bulkitsms.com/api/v2/account/credits" \
  -H "Authorization: Bearer bk_live_8n6JQv3K1h9Lp0Md"

Parameters

This endpoint does not require a JSON request body.

Authentication parameters

ParameterLocationRequiredTypeDescription
AuthorizationHeaderYes (recommended)stringBearer <your_api_key>
X-API-KeyHeaderOptional (legacy)stringYour Bulkit key
X-API-SecretHeaderOptional (legacy)stringYour Bulkit secret
apikeyQueryOptional fallbackstringAPI key used in URL authorization

Success response example

JSON
{
  "status": "success",
  "data": {
    "client_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "balance": 2.97,
    "bundle_credits": 429,
    "last_change": "2026-10-24T06:30:00Z",
    "currency": "KES"
  }
}

Response Fields

FieldTypeDescription
client_idstringUUID representing your Bulkit client account.
balancenumberAvailable cash float balance (in KES), accurate to 2 decimal places. Does not expire.
bundle_creditsintegerTotal active, unexpired SMS units remaining across all your Smart Bundles. These credits take priority over cash balance during SMS dispatch.
last_changestringISO 8601 timestamp of the most recent balance transaction.
currencystringWallet currency code (KES).

Error response examples

Invalid credentials

JSON
{
  "status": "error",
  "message": "Invalid API Key or Secret"
}

Unauthorized request

JSON
{
  "status": "error",
  "message": "Invalid API Key or Secret"
}

Notes and best practices

  • Credit Priority (FEFO): When dispatching SMS, Bulkit always consumes active bundle_credits first before debiting your cash balance. See Smart Bundles for full details.
  • Zero-Cash Sending: If you have active bundle_credits, you can successfully dispatch SMS even if your cash balance is 0.00.
  • Check balance before high-volume SMS or WhatsApp broadcasts.
  • Use Authorization: Bearer <token> in production systems.
  • Balances are returned as exact floating-point values (e.g. 2.97), enabling real-time micro-deductions per message unit.
  • The currency field is typically KES.
PreviousURL AuthorizationNextSmart Bundles