Skip to content
SMSRay
Print / PDF Download PDFFull reference PDF

Balance

Check how much you can send before you send it, and alert your team well before the balance runs out.

GET/sms/balance
https://api.smsray.com/api/sms/v1/sms/balance

Read your workspace balance, per-type rates, allowed message types and this API client's counters.

Request

Headers

Retrieve balance request headers
NameTypeRequiredRules
x-api-keystringrequiredYour secret key, ls_live_ followed by 48 hex characters.

Example request

curl https://api.smsray.com/api/sms/v1/sms/balance \
  -H "x-api-key: $SMSRAY_API_KEY"

Response

200

200 application/json
{
  "balance": 5000.0,
  "rate": { "transactional": 0.5, "otp": 0.5, "promotional": 0.5 },
  "allowedTypes": ["transactional", "otp"],
  "counters": { "sent": 120, "delivered": 110, "failed": 4 },
  "workspaceStatus": "active"
}

Response fields

Retrieve balance response fields
NameTypeRequiredRules
balancenumberrequiredCredit remaining for the current monthly period, in your workspace's currency (NPR for Nepal workspaces), shared by every API client in the workspace.
rateobjectrequiredPrice per SMS segment for transactional, otp and promotional. Cost = rate × segments. promotional is enabled only on Enterprise; check allowedTypes.
allowedTypesstring[]requiredMessage types this workspace may send. Others return 403 forbidden.
countersobjectrequiredThis API client's own sent, delivered and failed totals.
workspaceStatusstringrequiredactive, pending or suspended.

Errors

Every error uses the same shape: { "error", "code", "details"? }. Branch on code, not on the message.

Retrieve balance errors
HTTPcodeWhen
401unauthorizedThe x-api-key header is missing ("Missing x-api-key") or the key is unknown ("Invalid API key").
403client_disabledThe API client that owns this key has been disabled in the dashboard.
429rate_limitedYou exceeded your per-client request rate (default 20 requests per second). Honour Retry-After.
500server_errorSomething went wrong on our side. The body never contains a stack trace.

Notes

  • GET requests keep working while your workspace is pending, so you can integrate and check your setup before activation.
  • Your rate is your plan's per-SMS price. See pricing. Remaining balance expires at the end of each monthly period; top-ups are charged at your plan rate.
  • When the balance is lower than a message's cost, the send returns 402 insufficient_balance.
  • A message's cost is refunded only when delivery finally fails (failed). undelivered is not refunded.