Monitor a prepaid SMS balance by tracking days of runway, not dollars: divide the balance by your average daily burn, and alert when runway drops under a set number of days. Burn is segments per day times the per-segment rate, so you can forecast it from your own usage rows before the balance gets low.
This matters most for a platform, because one balance serves every customer you text for. If it runs dry on a Friday night, every customer's reminders, codes and alerts stop at once, and none of them did anything wrong. Ready bills prepaid credits, so this applies to us directly. We'll cover thresholds, the forecast, a worked example with stated assumptions, and a top-up runbook.
Where to read the balance
The dashboard shows your balance under Billing. If you work with an AI agent over MCP, the server can read billing too, so an agent can answer "how much runway do we have?" without anyone opening the dashboard. The MCP docs list the tools.
In code, read it from GET /v1/account: data.balance_usd is your balance rounded to cents, and data.balance_cents is the exact figure. The balance and rates docs list the rest of the response. The monitor in this post reads the balance from that call and computes a burn figure from your own data. If the call fails, report the balance as unknown instead of reusing an old number.
Why runway beats dollars
A fixed dollar alert, like "warn me under $100", is wrong in both directions. It fires constantly for a small platform and too late for a growing one. Runway scales with you.
| Metric | What it answers | Weakness |
|---|---|---|
| Balance in dollars | How much is left | Says nothing about how fast it goes |
| Days of runway | How long until zero at the current rate | Needs a burn estimate |
| Forecast with a spike factor | Will a planned campaign day empty it | Needs your product calendar |
Use runway as the primary alert and keep one dollar floor as a backstop, for the day your burn estimate is wrong.
Forecast burn from segments times rate
Ready bills per segment, and a segment isn't a message. One emoji can turn a 140-character text into 3 segments instead of 1. Count segments in your own usage rows, as in metering SMS usage per customer, and use the real rate from the pricing page.
Per segment, a sent text costs $0.0075 plus a $0.0045 carrier fee, so $0.012 all-in. A reply you receive is billed the same way, at the per-segment rate plus a $0.003 carrier fee, so replies belong in the forecast too. The all-in figure leaves out screening, which applies only if you've switched on Scrub lists or Number validation. There's no volume discount, so burn is linear. Accounts opened before November 12, 2026 keep their signup prices, shown under Billing.
Ready's all-in prices per segment include the carrier fee but not screening: Scrub lists and Number validation, the two switches in Settings under Compliance, each add $0.003 per segment when switched on, shown as screening on your bill, and both are off by default. Unless you turn the opt-out footer off, the first text to each contact, and one again from time to time, also gets "Reply STOP to opt out" and your business name if the message does not already have them, so a text close to the segment limit can bill one more segment.
A worked example
These are assumptions for illustration, not a forecast of your numbers.
- 30 customers on your platform, each sending 400 texts a month, so 12,000 texts.
- An average of 1.5 segments per text, so 18,000 sent segments.
- 2,400 replies a month, 1 segment each.
- 30 days in the month, and an opening balance of $500.
The sent side: 18,000 × $0.012 = $216.
The reply side: 2,400 × ($0.0075 + $0.003) = $25.20.
That's $241.20 a month, or $8.04 a day. A $500 balance is about 62 days of runway at that rate.
Now derive thresholds from the daily burn:
| Alert | Runway | Balance at $8.04 a day |
|---|---|---|
| Notice | 14 days | $112.56 |
| Warning | 7 days | $56.28 |
| Page someone | 3 days | $24.12 |
Add a spike check. Suppose one customer onboards and sends a 3,000-text welcome campaign at 1.5 segments each. That's 4,500 segments, and 4,500 × $0.012 = $54. A $56.28 warning balance would cover it by a hair. If you know a launch is coming, top up first and don't rely on the threshold.
The alert code
This sketch reads the balance from GET /v1/account and takes seven days of segment counts from your own tables. The rates are constants you copy from the pricing page. Update them when pricing changes.
export async function readBalanceUsd(apiKey) {
const res = await fetch("https://api.tryready.com/v1/account", {
headers: { "X-API-Key": apiKey },
});
if (!res.ok) throw new Error(`balance read failed: ${res.status}`);
const { data } = await res.json();
if (data.balance_usd == null) throw new Error("balance unknown");
return data.balance_usd;
}
const SENT_RATE = 0.0075 + 0.0045; // rate plus carrier fee per segment
const REPLY_RATE = 0.0075 + 0.003; // received segment
export function burnPerDay(daily) {
// daily: [{ sentSegments, receivedSegments }, ...] for the last 7 days
const cost = daily.reduce(
(sum, d) => sum + d.sentSegments * SENT_RATE + d.receivedSegments * REPLY_RATE,
0,
);
return cost / daily.length;
}
export function runwayDays(balanceUsd, daily) {
const burn = burnPerDay(daily);
return burn === 0 ? Infinity : balanceUsd / burn;
}
export function level(days) {
if (days < 3) return "page";
if (days < 7) return "warning";
if (days < 14) return "notice";
return "ok";
} Run it from a daily job, post the result to a channel your team reads, and store the last level so you only alert on a change. Alerting on every run trains people to ignore it. For where this fits with the rest of your logging, see observability, logging and alerting.
Consider running it a second time on the last day alone. A weekly average hides a sudden jump.
What happens when the balance runs low
Treat an empty balance as a failure mode your code must survive. A send the balance can't cover answers 402 insufficient_balance, with balance_cents and required_cents in the body, and a bulk call answers 402 insufficient_credits. Nothing is sent or charged, so sends are refused, not delayed. The error codes reference lists both; branch on the code, not the message text.
That shapes your queue. A refused send should go to a retry path with a visible state, not vanish. Retries and failure handling covers the pattern, and a refused send comes back with will_resend in the body. When it is true, Ready kept the text and sends it by itself if you top up within the hold window, so don't replay it. Separate your critical traffic, like login codes and alerts, from marketing so that when you must triage, you know what to send first.
A top-up runbook
Write this down before you need it. A runbook that lives in someone's head fails when that person is on a plane.
- Confirm the balance. Read it from Billing or
GET /v1/account, not from your alert state, in case the alert is stale. - Decide the amount. Pick the days of runway you want, then multiply by daily burn. At $8.04 a day, 30 days of runway needs about $241.
- Add credits. Use the Billing page. Name the person who can do this and a backup, since paying usually involves a card or an approver.
- Read the new balance from
GET /v1/account, and clear the alert state. - Replay what Ready did not keep from your retry queue, in priority order: refusals where
will_resendisfalse. CheckGET /v1/messagesfirst, and use a new idempotency key, because the old key replays the stored 402. Leavewill_resend: truerefusals alone. - Review the miss. If you hit zero, adjust the thresholds or the cadence of your top-ups.
A note on passing the cost on
If you bill your customers for texting, the balance is your cash and the usage is their invoice, so the two have to reconcile. Usage-based billing alerts covers the customer-facing side, and forecasting SMS costs for a new feature helps before you launch something that changes your burn.
The takeaway is small: compute runway, alert on it in tiers, know your top-up steps, and make sure an empty balance degrades into a queue and not into lost texts.