Client and Balance Management¶
The platform separates the organization that owns the commercial account from the users who sign in and use its balance. An organization can manage one shared balance and optionally set a separate balance limit for each user.
Organization onboarding¶
An internal operator can register a client with:
- organization and contact details;
- unique primary email and optional secondary email;
- prepaid or postpaid payment type;
- initial available balance;
- postpaid credit limit where applicable;
- DLR-aware reporting preference.
New clients are created ACTIVE with a matching balance record. Registration does not create credentials; users are provisioned separately.
Organization and user hierarchy¶
flowchart TB
Client[Client organization\navailable balance + payment policy]
U1[User 1\nseparate balance limit]
U2[User 2\nuses organization balance]
U3[User 3\nuses organization balance]
Client --> U1
Client --> U2
Client --> U3| Concept | Business meaning |
|---|---|
| Client | Legal/commercial tenant that owns balance and payment policy |
| Client user | Login identity belonging to one client; creates messages/campaigns |
| Available balance | Current organization balance, reduced when SMS is charged |
| Allocated balance | Optional balance limit for one user; without a limit, the user spends from the organization's shared balance |
| Credit limit | Amount a postpaid organization can spend after its balance reaches zero |
Operators can create users, list them, reset passwords, change status, set a separate balance limit, or remove that limit so the user spends from the organization balance. Usernames allow letters, digits, ., _, and -; passwords must be at least eight characters.
How prepaid and postpaid balances work¶
| Payment type | Spending rule | Typical use |
|---|---|---|
PREPAID |
The available user or organization balance must cover the full charge | Deposit-before-use accounts |
POSTPAID |
Users spending from the organization balance can use the approved credit limit | Contract customers with approved credit |
Postpaid accounts require a credit limit of zero or more. Prepaid accounts do not use a credit limit.
User balance options¶
An operator can give a user a separate balance limit or let the user spend from the organization's shared balance. Setting a user limit does not immediately reduce the organization's available balance. The amount available to shared-balance users is:
User with shared organization balance¶
- The user has no separate balance limit.
- A prepaid user can spend the unallocated organization balance.
- A postpaid user can also use the organization's approved credit limit.
- Each charge reduces the organization balance.
User with a separate balance limit¶
- The user has a limit of zero or more.
- Both the user's limit and the organization balance must cover the charge.
- Each charge reduces both balances by the same amount.
- A postpaid credit limit does not override the user's separate limit.
When an operator changes a user limit, the platform checks that all user limits together do not exceed the organization balance. It also protects the balance from conflicting updates made at the same time.
Checking and charging the balance¶
Before accepting an SMS or campaign, the platform calculates the cost and checks that enough balance is available:
recipient cost = (message segments × tenant/channel/operator rate) + DI price
total charge = sum(all recipient costs)
The balance check and charge happen together, preventing two requests from spending the same funds. An inactive user cannot be charged.
Campaign charges use a unique request key, allowing the same charge to be retried safely. A charge without a request key should not be retried when its result is unclear; check the balance first.
Top-up and manual balance operations¶
An operator can add a positive amount to a client's available balance.
The platform does not currently support:
- balance withdrawal;
- payment-type or credit-limit changes;
- client status changes;
- client/user deletion;
- tenant self-service top-up;
- a general transaction-history endpoint.
Returning funds¶
The platform can return funds in two situations:
| Operation | When it is used | If repeated |
|---|---|---|
| Undo charge | A request fails after the balance may have been charged | The balance is not returned twice |
| Refund | A message or campaign has an eligible final failure | The balance is not returned twice |
Returning funds increases the organization balance. If the user has a separate balance limit at that time, that balance also increases. Because the original balance source is not saved, operators should avoid changing a user's balance limit while a return is unresolved.
Only trusted internal services can issue refunds.
See the Client and User Administration API, Balance Operations API, and client-service processes.