Who pays, and who is limited
A send needs both: a unit on the units account and credit on the parent. Units are a limit, not
prepaid money. A three-part message takes three units.
A units account is always a direct child of an account that holds money. A units account cannot have
children of its own.
How units are counted
Units are counted by the same engine that counts prepaid credit: each gateway node reserves a block, spends it from memory with no database call per message, and settles what was spent. The count is exact after a crash.- A refunded message gives its unit back, once: a vendor refusal, an expiry, a drop, a message that could not be queued.
- Small allowances are shared fairly. A node never reserves more than its share of what is free, and hands back a block it has not used for a few seconds, so five units on a two-node gateway are five sendable messages, whichever node the customer reaches.
- Units are enforced wherever prepaid credit is. On a gateway with prepaid enforcement off, a units account’s logins are not loaded and cannot bind or send: nothing would be counting them.
What a customer sees when it runs out
Nothing is charged for any of the three, and in the third the unit is given back.
0x403 is deliberately not the no-credit 0x402: a customer can tell “I am out of units” from “my
provider is out of money”. The status is set per listener with conf.status.noUnits, in hex or
decimal; the default is 0x00000403.
unitsPending is the only one worth retrying: units held elsewhere come back within seconds.
Where units accounts come from
A units account is created, given units and taken units from by the platform that manages it (FireFlo OMNI, for example) over the gateway’s management API. The control panel shows units accounts and their ledger; it does not create them or move units. Every give, take-back and move is written to an append-only unit ledger under a reference, and a repeat with the same reference changes nothing. For every account and product, free + reserved + used equals the sum of its ledger. A platform can create units accounts only while prepaid enforcement is on and every running gateway node is 0.16.0 or newer. During a rolling upgrade that begins once the last older node is gone. An existing account is never converted. A money account stays a money account; a units account is a new account under the parent. Money cannot be moved to or from a units account: top-ups, debits and credit transfers naming one are refused.What a units login cannot do
A units login is not its parent on the self-service API.- Balance answers its own units, never the parent’s money — see Balance.
- An accepted send does not show the parent’s price.
- The rate quote, credit transfers, sender ID and template registrations and the batch list answer
403with codeUNITS_LOGIN. Those belong to the account that pays.
How fast it may send
A units account can have a speed limit of its own, on top of its parent’s. The platform that manages it sets it; two values, either of which may be left unset.
Precedence. A submit is checked against the units account’s own limit first. Over it, the submit is
refused without drawing on the parent’s limit, so one customer sending too fast does not use up its
reseller’s allowance. Within it, the parent’s limits apply as they always did: the parent’s own
conf.maxRate, the listener’s default and the port’s budget. A login with a faster limit of its own is
still held to its units account’s limit.
0x58 means “slow down”; 0x14 means “try again shortly”. Empty or 0 means the units account has
no limit of its own, and only the parent’s apply.
A units login’s binds count against its parent’s connection limit. There is no separate bind limit per
units account.
In the control panel
A units account’s page says units in place of a balance and names the account it is charged to. Its Billing tab shows units left and used per product, its logins, units used this month and by day, its speed limits and the unit ledger. The Tariff and Statement tabs are not shown: prices and the statement are the parent’s. No money action is offered. A parent’s Billing tab lists its sub-accounts, with units left per product and a “no units” state. If units accounts cannot be used yet, because a node is older than 0.16.0 or prepaid enforcement is off, the tab says which. Refused messages appear on Refused under No units left and Units being reserved; try again. The account shown there is the parent, which pays; the login is the units account’s.Upgrading to 0.16.0
The schema moves from 1.129.0 to 1.131.0, so update with--migrate. It adds empty unit tables and one
nullable column on the call record. An installation with no units accounts behaves as it did on
0.15.13. One key is new, conf.status.noUnits; nothing has to be set.
Update the control panel with the gateway: an older panel reports the schema as newer than it expects.
Related
Prepaid credit
The engine units are counted by.
Status codes
0x403, and what it is deliberately not.