Credits API

Check how many SMS credits a project has left and whether auto top-up is switched on. One authenticated GET request returns both.

GET/sms/credits/

Get SMS credits

Retrieve the project's SMS credit balance and its auto top-up status. The project comes from the API key, so there is nothing to pass. Returns 401 Unauthorized if the key is missing or revoked, or if the account is suspended.

Response Fields

balanceinteger

The credits the project can spend right now. This is a count of credits, not messages. A standard 160-character message uses one credit per recipient, and a longer or non-GSM message uses one per segment.

auto_topup.enabledboolean

Whether auto top-up is switched on. The auto_topup object is always in the response, even for a project that has never set it up.

auto_topup.thresholdinteger

The balance that triggers a top-up. 0 if auto top-up has never been set up.

auto_topup.topup_quantityinteger

How many credits each top-up buys. 0 if auto top-up has never been set up.

200 OKResponse

{
  "balance": 1240,
  "auto_topup": {
    "enabled": true,
    "threshold": 100,
    "topup_quantity": 500
  }
}

Low balances

A low balance only stops sends when auto top-up is off. With it on, a send that runs past the balance still goes through. The recipients the balance covers go out at once, and the rest wait in pending_balance until the top-up lands. With it off, the whole send is rejected with insufficient_balance and nothing goes out. So check enabled before you warn anyone about the number.

If enabled is false but the threshold and quantity are not 0, those are the saved settings. Switching auto top-up back on in the dashboard uses them as they are. Auto top-up is managed in the dashboard and needs a card on the account. There is no endpoint for changing it.

The endpoint only returns the live balance. It leaves out lifetime purchases and the total since the last top-up, so it cannot reproduce the credit gauge in the dashboard header. Use the dashboard for that.

Check before a send — Node.js

const res = await fetch("https://api.sailup.io/v1/sms/credits/", {
  headers: { Authorization: "Bearer " + process.env.SAILUP_API_KEY },
});
const { balance, auto_topup } = await res.json();

// A two-segment body costs two credits per recipient.
const needed = recipients.length * segments;

if (balance < needed && !auto_topup.enabled) {
  // The send would be rejected with insufficient_balance.
  alertOps("SMS balance is " + balance + ", send needs " + needed);
}