Automating SIM Balance Top-Up via API: What Has to Exist First

Automating SIM balance top-up via an API is presented as an integration task and is really a dependency problem. The code is the easy part; what decides whether automation works is whether a machine-readable balance can be obtained at all.

This article sets out what the automation actually requires, the three ways a prepaid balance can be read and what each one costs in reliability, how to design around a failed check, the alerting thresholds that prevent a mid-campaign surprise, and the log fields that make reconciliation possible afterwards.

What does automating SIM balance top-up via an API actually depend on?

A readable balance, a writable top-up path and a slot map.

Automation needs a machine-readable balance, a top-up interface that can be called programmatically, and a stable mapping between each subscription and the slot that holds it.

The mapping is the requirement that gets overlooked. Even a perfect balance API is useless if the platform cannot say which physical slot holds the subscription whose balance it just read, because the action that follows — topping up the right card or moving it out of service — depends on that link. Build the mapping first and the rest of the integration becomes straightforward.

The second requirement is an interface that returns a value rather than a message intended for a person. A balance service that answers in a screen designed for a human is readable by a person and fragile in a program, because small presentation changes break the parser. Where the only available path is human-oriented, the automation should be designed around sampling rather than around real-time control.

How do you read a prepaid balance: USSD, portal or operator API?

Three paths exist, and they differ mostly in stability.

USSD is universally available and least stable to parse, a carrier portal is workable for scheduled checks, and a documented operator API is the only path designed for automation.

USSD is a session-based service carried over the signalling channel, and the command interface that equipment uses to send and receive it is standardised in ETSI TS 127 005, with the corresponding 3GPP specification at 3GPP TS 27.005. Two properties make it awkward for automation. The reply is text intended for display, so the parser has to cope with localisation and with wording changes, and the session occupies the radio path for the duration, which puts a check in competition with message traffic on the same slot.

A carrier portal is the middle option. It is reliable enough for a scheduled daily sweep, and it does not consume the radio path, but it is still a human interface and it introduces a session, a credential and a rate limit that the integration does not control. Treat a portal-based check as a scheduled task rather than as a real-time signal.

A documented operator API is the only path that behaves like an interface: a request, a response, a defined error space, and a rate limit the operator publishes. Where one is available for the market, the integration should be built on it and the other paths should be treated as fallbacks.

Balance path	Best use	Main weakness
USSD	Availability when nothing else exists	Display text, radio occupancy, concurrent with messaging
Carrier portal	Scheduled daily sweep	Human interface, session dependencies, rate limits
Operator API	Real-time thresholds and automation	Availability by market and by account type
Local counter	Estimating between checks	Drifts from the operator’s figure

Where the third-party dependency sits

Somewhere outside your control, and it should be named.

Every balance path depends on a party that is not you: the operator, the portal provider, or a reseller whose API sits between the two.

The dependency matters because it determines what an incident looks like. If the balance service is unavailable, the automation cannot distinguish a card with no credit from a service that is simply not answering, and those two states call for opposite responses. Naming the dependency in the design is what allows the failure to be classified correctly at the time rather than investigated afterwards.

Where a reseller sits in the path, the failure modes multiply, because the operator may be healthy while the intermediary is not. For that reason, deployments that operate across several markets usually keep the balance integration per market rather than building one abstraction over all of them, since the abstraction hides exactly the difference that matters when something breaks.

Message delivery itself depends on the short message service centre described in ETSI TS 123 040, and the same principle applies there: the operator’s systems can be healthy end to end while your integration cannot see them.

What should happen when a balance check fails?

Nothing automatic, and the failure should be visible.

A failed check should leave the previous state in place, raise a distinct alert and never be interpreted as a zero balance, because the two conditions require opposite actions.

The distinction between “cannot read” and “read zero” is the single most important design decision in this integration. A system that treats an unreadable balance as empty will stop sending on healthy cards during a portal outage, which converts a monitoring problem into a service outage. A system that treats an unreadable balance as healthy will send on an empty card, which produces a burst of failures and an unnecessary operator conversation.

The workable behaviour is a third state. Record the last known value and its timestamp, mark the reading as stale, continue sending within the policy ceiling, and alert when the stale period exceeds the threshold the operation can tolerate. That design keeps the automation useful during a partial outage while keeping the failure visible.

Alerting thresholds that avoid a mid-campaign surprise

Set the threshold from burn rate, not from a round number. A card consumed at a known rate reaches a given level at a predictable time, so the alert threshold should be derived from how long it takes to replenish rather than from a figure that looks comfortable. Where replenishment is manual, the threshold has to cover the human step, which is usually the longest part of the chain.

Two thresholds work better than one. The first warns while there is still time to act without interrupting traffic. The second is an operational stop, after which the platform removes the number from the rotation rather than letting it fail in the middle of a batch. The second threshold is what turns an alert into a control, and it is the one that prevents the failure mode this automation exists to remove.

Alert on the trend as well as on the level. A card whose consumption rate has doubled will cross the threshold sooner than the level suggests, and the rate change is often the more useful signal because it identifies the campaign that caused it.

What to log for reconciliation

Log the reading, the source and the outcome. For each check, record the timestamp, the subscription identifier, the slot, the balance path used, the value returned and the response time. For each top-up, record the amount, the request identifier, the outcome and any operator reference. Guidance on the content and retention of operational records is available in NIST SP 800-92, and the fields above are the minimum that survives a dispute.

Reconciliation is the reason to keep both sides of the record. When a card is suspended or a top-up is disputed, the deployment has to show what it read and what it did, and the two are usually held in different systems. Keeping the request identifier with both halves is what makes the join possible; without it, the log supports an opinion rather than a fact.

Numbers should be stored in normalised form throughout, which is the convention established by the ITU-T E.164 plan, so that a subscription read from one system matches the same subscription in another.

A minimal implementation shape

A small implementation beats an ambitious one. Start with a scheduled sweep that reads every balance once a day, stores the value with its timestamp, and compares it against the two thresholds. Add the top-up call only where the path is documented and idempotent, and keep a manual fallback for every market where it is not.

1. Map every subscription to a stable slot identity before writing any integration code.
2. Read balances on a schedule and store value, timestamp and source.
3. Mark unreadable checks as stale rather than as zero.
4. Derive warning and stop thresholds from replenishment time.
5. Remove numbers from rotation at the stop threshold instead of letting them fail.
6. Keep the request identifier with both the read and the write for reconciliation.

Where the integration exposes or consumes network services, assign service names and ports deliberately rather than by habit; the registries maintained by the Internet Assigned Numbers Authority, including the service name and port registry, are the reference for that choice.

Two operational habits keep the implementation useful after the first month. The first is to schedule the sweep at a fixed time and to record its duration, because a sweep that starts drifting later into the day eventually collides with peak traffic. The second is to review the threshold policy whenever the message profile changes, since a threshold derived from one campaign size is the wrong threshold for the next one.

{
“@context”: “https://schema.org”,
“@type”: “FAQPage”,
“mainEntity”: [
{
“@type”: “Question”,
“name”: “Can balance automation work without an operator API?”,
“acceptedAnswer”: {
“@type”: “Answer”,
“text”: “It can, using USSD or a carrier portal, but the reliability is lower and the failure modes are harder to classify. Treat those paths as a scheduled sweep rather than as real-time control, keep a manual fallback for each market, and design the alerting so that an unreadable balance is never interpreted as an empty one. Log the raw response as well as the parsed value, because the raw text is what you will need when a market changes its reply format.”
}
},
{
“@type”: “Question”,
“name”: “How often should balances be checked?”,
“acceptedAnswer”: {
“@type”: “Answer”,
“text”: “Often enough to cover the replenishment step, and no more often than necessary. Where top-up is automatic, a daily sweep with trend alerting is usually sufficient; where it is manual, the interval has to cover the human task. More frequent checks add load and dependency exposure without improving the outcome. Where a carrier limits request frequency, spacing the checks also keeps the integration inside whatever the operator will tolerate.”
}
},
{
“@type”: “Question”,
“name”: “What is the biggest design mistake in these integrations?”,
“acceptedAnswer”: {
“@type”: “Answer”,
“text”: “Treating an unreadable balance as zero. That single decision converts a monitoring outage into a service outage by removing healthy numbers from rotation. Keep the last known value, mark it stale, and let the alert threshold rather than the absence of data drive the action. The stale marker should also suppress automatic top-up, since a failed read is not evidence that credit is needed.”
}
},
{
“@type”: “Question”,
“name”: “Why does the slot mapping matter so much?”,
“acceptedAnswer”: {
“@type”: “Answer”,
“text”: “Because a balance without a location cannot be acted on. The mapping is what lets the platform top up the right card, move the right number out of rotation, and reconcile an operator reference against a physical slot. Build it first; everything else in the integration depends on it. Where the estate spans several banks, the mapping also has to record which bank holds the card.”
}
}
]
}