Credit and Billing

TopCalls runs on prepaid credit in US dollars. Your account has one balance, and calls draw on it. There’s no subscription or plan tier, and credit never expires. The error code insufficient_quota means not enough credit.

Adding Credit

Credit is bought in the dashboard. There is no API to buy credit. Only people who can manage billing on the account see this pane. If you can’t, ask the account owner. Credit never expires. Calls are billed by the second as they run, and whatever you don’t spend stays on the balance. Extra concurrent-call slots and browser dialer seats, both monthly fees, are paid from it too. For a system nobody watches, turn on auto-recharge in Settings > Billing: it buys credit when the balance runs low, in charges of $100 or more, so a long campaign doesn’t stop partway.

How Calls Are Charged

A minute costs the AI part plus the line, and the line depends on the destination’s zone. A call placed by hand in the browser dialer pays the line alone, and each person who uses it pays a $29 monthly seat. Pricing and Zones lists every price, including test calls and calls on your own carrier, and links to the country lookup. To see what a number costs before you dial it, ask GET /v1/pricing/quote. An account on a negotiated price pays that one price for every AI call, whatever the destination or the carrier. Talk time is billed per second and rounded up to the whole second. Nothing else is metered on a call. A call that fails on our side before the agent speaks isn’t charged, and no spend for it appears in GET /v1/usage/movements.

Starter Credit

A new account gets $10 of starter credit for real calls before paying anything. It pays for calls only: it can’t be transferred to another team or spent on extra concurrency slots or dialer seats. Calls spend starter credit first, then purchased credit.

How a Call Holds Credit

Placing a call holds credit for its full max_duration at the call’s own price per minute, not the time it uses. The unused part comes back when the call ends. Overlapping calls each hold their maximum, so a new call has less to draw on than your balance suggests. A shorter max_duration holds less. What that comes to, on standard prices: A call on your own carrier is held at $0.15 a minute, so a default `POST /v1/calls` holds $0.75. The hold shows as reserved_micros in GET /v1/balance.

Running Out

If the hold doesn’t fit, POST /v1/calls returns 402 with code: insufficient_quota. Nothing is charged or queued. Insufficient quota shows the error body. Campaign start and resume also return 402 unless available credit covers one call’s full max_duration at rate.per_minute_micros. A campaign test call holds credit for the campaign’s max_duration (5 minutes when the campaign sets none, where start counts 10) at the price of that call. In a running campaign, a dial that doesn’t fit waits if calls in progress are holding the credit it needs. If your whole balance can’t cover it, every running campaign on the account pauses with pause_reason: quota_exceeded. Add credit, then resume. One exception: a number priced above rate.per_minute_micros (a dearer range inside a country you have enabled) while your balance still covers a call at that rate. Only that call ends, failed with error_message “Insufficient credit for this destination” and uncharged, and the campaign keeps dialing its other leads. The lead is tried again on the campaign’s retry schedule, up to its maximum attempts, so credit added before then lets it dial. A call booked with scheduled_at holds nothing until it’s due. If the hold doesn’t fit then, it ends failed with error_message “Insufficient credit at scheduled time”, uncharged and not retried.

Checking Your Balance

GET /v1/balance reports credit in integer microdollars ($1 = 1,000,000), plus rate, concurrency slots and auto-recharge settings. rate.pricing_model is zones or contract (a negotiated price). rate.per_minute_micros is what a minute is counted at before a call knows its destination: your negotiated price on contract, and on zones the AI price plus the Zone 2 line, or the Zone 3 line when you have a Zone 3 country enabled. Campaign start and resume need credit for one call’s full max_duration at that price. A single call is held at its own price. For example, a standard account shows per_minute_micros: 350000, which is $0.35: the AI part ($0.15) plus the Zone 2 line ($0.20). A call to a Zone 1 country still costs $0.25. Starting a campaign with the default 10 minute limit needs $3.50 of available credit, because a start counts at the dearest rate you can dial. A refused start or resume returns required (minutes) and price_per_minute_usd: 0.35; a refused single call returns requested. GET /v1/usage/movements lists the ledger Billing shows. Each row has kind, a signed amount_micros (a call spend is negative), balance_after_micros, talk_seconds on a call and source_id (the call id for a spend). Holds for calls in progress aren’t listed. The API reference has both endpoints and the scope they need.

Units

What a Call Cost

Each call carries the price it was placed at, and what it cost once it has been charged:

• price_per_minute_usd: dollars per minute, set when the call is dialed (a call booked with scheduled_at has none until it’s due). It is the price the call is charged at.
• cost_usd: dollars charged, read from the same credit ledger entry that GET /v1/usage/movements lists as the call’s spend. It is null while the call runs and until the charge lands, and "0.00" for a call that ended with 0 minutes billed. A call that never dialed (refused, or cancelled while queued) has neither a price nor a cost.

Both are exact decimal strings, such as "0.25" and "0.0625", on GET /v1/calls/{call_id} and in GET /v1/calls.

Concurrency

Every account includes 20 concurrent calls. Extra slots cost $15 a month each, paid from purchased credit, and you can add as many as your volume needs in Settings > Billing: accounts run 1,000+ calls at once this way. Prices stay the same however many calls run. Inbound calls use slots too but never get a 429. They have their own cap of 5 at a time per account, and further callers are declined. A campaign waits for a free slot by itself. A single call or campaign test call placed while every slot is busy returns 429 with code: concurrency_limit.

Auto-recharge and Alerts

Auto-recharge buys credit when you run low, so a long campaign doesn’t stop partway. Alerts only notify you. Both start off; turn them on in Settings > Billing. Before a big scheduled batch, check credit.available_micros: a scheduled call that finds too little credit when it comes due fails uncharged.

Next Steps