Platform
Balance, usage and pricing
Read your prepaid balance, what you spent per day, channel and destination, and the prices your plan charges — straight from the billing ledger.
Trovacast bills from prepaid credit: calls per started minute (one minute minimum once answered), messages per message or SMS segment, numbers monthly. A key with billing:read reads all of it. A key with billing:manage starts top-ups — a checkout link a person pays; plan changes happen in the console. Test traffic is never billed, so it never appears in usage.
- GET
/v1/balanceRetrieves the prepaid balance, this period’s included minutes and the plan enrolment - GET
/v1/usageLists spend per UTC day, channel and destination over a window of at most 90 days - GET
/v1/pricingRetrieves the plan’s prices: the per-minute cells (by channel, call type and destination) and the per-message cells - POST
/v1/balance/top-upsStarts a credit top-up: returns a hosted checkout link for a person to pay - GET
/v1/balance/top-ups/{topUpId}Retrieves a top-up; a pending one is checked with the payment gateway (and credited if paid)
Balance
Your wallet in minor units of currency (paise for INR), this period’s included call minutes and your plan enrolment. The balance can be negative: a call admitted on one minute of credit runs to its end, and the next dial is refused until you top up. A subscription that is past_due refuses dials and sends until a top-up settles the plan’s fee.
curl 'https://api.trovacast.com/v1/balance' \
-H "Authorization: Bearer $TROVACAST_API_KEY"{
"object": "balance",
"currency": "INR",
"availableMinor": 340100,
"lowBalanceThresholdMinor": 20000,
"includedMinutes": {
"total": 500,
"used": 120,
"remaining": 380
},
"subscription": {
"status": "active",
"plan": {
"code": "GROWTH",
"name": "Growth"
},
"currentPeriodStart": "2026-11-01T00:00:00.000Z",
"currentPeriodEnd": "2026-12-01T00:00:00.000Z",
"trialEndsAt": null,
"cancelAtPeriodEnd": false
},
"updatedAt": "2026-11-05T09:58:12.000Z"
}Usage
Spend per UTC day × channel × destination, oldest day first; days with nothing spent are left out. Ask for a window with from (inclusive) and to (exclusive) — ISO 8601 dates or date-times — of at most 90 days; without them you get the last 30 days, today included. channel narrows to one of voice, sms, whatsapp, email, numbers (setup fees and rentals) or plan (the monthly fee). A parent reads one of its subaccounts’ spend the same way with subaccountId (its key also needs subaccounts:read); the answer’s subaccountId says whose rows they are. An integration’s billing organization — the account that pays for the organizations its integration bills to it — breaks its spend down with breakdown=organization: each row then names its organizationId, and its monthly statements carry paidFor.
curl 'https://api.trovacast.com/v1/usage?from=2026-10-01&to=2026-11-01&channel=voice' \
-H "Authorization: Bearer $TROVACAST_API_KEY"{
"object": "usage",
"from": "2026-10-01T00:00:00.000Z",
"to": "2026-11-01T00:00:00.000Z",
"data": [
{
"date": "2026-10-04",
"channel": "voice",
"destination": null,
"currency": "INR",
"count": 12,
"unit": "minute",
"billedUnits": 31,
"includedUnits": 31,
"amountMinor": 0
},
{
"date": "2026-10-04",
"channel": "voice",
"destination": "GB",
"currency": "INR",
"count": 3,
"unit": "minute",
"billedUnits": 7,
"includedUnits": 0,
"amountMinor": 2100
}
]
}| Channel | `count` | `billedUnits` | `destination` |
|---|---|---|---|
voice | Calls rated, answered or not | Minutes billed (includedUnits of them covered by the plan’s bundle) | The rate cell that priced the calls — a country (GB) or a prefix (+447); null for the every-destination price |
sms | Messages charged | Segments | The destination country |
whatsapp, email | Messages charged | Messages | null |
numbers, plan | Ledger entries | Fees | null |
amountMinor is what was spent. Refunded messages (a send that failed after it was charged) are not spend; a plan change’s credit back makes plan negative for that day. A window over 90 days, or one that ends before it starts, is 400 VALIDATION_FAILED — ask for several.
Invoices
A monthly statement of the prepaid balance, one per UTC calendar month: the balance it opened and closed on, credits by kind (top-ups, trial credit, adjustments, refunds), spend by channel (voice, SMS, WhatsApp, email), number fees and plan fees. It always balances — the opening balance plus every line is the closing balance. GET /v1/invoices lists months newest first (before pages back), GET /v1/invoices/{period} reads one (2026-10) GET /v1/invoices/{period}/csv downloads it as CSV, and GET /v1/invoices/{period}.pdf (or Accept: application/pdf) as a one-page PDF. The running month reads status: open. A statement records how prepaid credit was spent; tax invoices for top-ups come from the payment gateway.
curl 'https://api.trovacast.com/v1/invoices/2026-10' \
-H "Authorization: Bearer $TROVACAST_API_KEY"Top-ups
POST /v1/balance/top-ups (scope billing:manage, live keys only) starts a credit top-up and answers a hosted checkout link: send a person there to pay. The call itself moves no money — your wallet is credited once, when the payment gateway reports the payment. amountMinor is at least your plan’s minimumTopUpMinor (BILLING_TOP_UP_BELOW_MINIMUM) and at most the online limit (BILLING_TOP_UP_ABOVE_MAXIMUM); successUrl and cancelUrl (https) are where the payer lands — your billing page in the console if you leave them out.
curl -X POST 'https://api.trovacast.com/v1/balance/top-ups' \
-H "Authorization: Bearer $TROVACAST_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H 'Content-Type: application/json' \
-d '{
"amountMinor": 100000,
"successUrl": "https://app.example.com/billing/thanks",
"cancelUrl": "https://app.example.com/billing"
}'{
"object": "top_up",
"id": "8e1d2c3b-4a59-4687-9a0b-1c2d3e4f5a6b",
"status": "pending",
"amountMinor": 100000,
"currency": "INR",
"checkoutUrl": "https://checkout.stripe.com/c/pay/cs_live_a1b2c3",
"expiresAt": "2026-11-07T10:00:00.000Z",
"createdAt": "2026-11-06T10:00:00.000Z"
}GET /v1/balance/top-ups/{topUpId}reads it back; apendingtop-up is checked with the payment gateway and credited if it was paid, so you can follow it without a webhook.status:pending,succeeded,failed,expired(the link stops working atexpiresAt, 24 hours) orrefunded.checkoutUrlcomes back from the create call only. Lost it? Start another top-up — the abandoned one expires.- Send an
Idempotency-Key: a retried create answers the same checkout. A deployment without online payments answersBILLING_PAYMENTS_UNAVAILABLE.
Low-balance alert
PATCH /v1/balance with { "lowBalanceThresholdMinor": 50000 } (scope billing:manage — a setting, not money) sets the balance below which the console warns your administrators and the balance.low event fires. It fires once per crossing — when an entry takes the balance from at or above the threshold to below it — and again only after a top-up lifts it back over. 0 turns it off. Calls and messages carry charge (amount, currency, units, status) once they are rated.
Pricing
Your plan’s rate cards exactly as they are set: what each call minute costs by direction, channel, call type and destination, and what each message costs by channel and category (SMS by destination country, per segment). A combination that is not listed is not offered on your plan — such a call or send is refused with BILLING_RATE_UNAVAILABLE. Number prices are per number: see Phone numbers.
curl 'https://api.trovacast.com/v1/pricing' \
-H "Authorization: Bearer $TROVACAST_API_KEY"{
"object": "pricing",
"plan": {
"code": "GROWTH",
"name": "Growth",
"currency": "INR",
"monthlyFeeMinor": 99900,
"includedMinutes": 500,
"trialDays": 0,
"minimumTopUpMinor": 50000
},
"voice": [
{
"direction": "outbound",
"provider": "plivo",
"callType": "manual",
"destination": null,
"ratePerMinuteMinor": 150
},
{
"direction": "outbound",
"provider": "plivo",
"callType": "manual",
"destination": "+447",
"ratePerMinuteMinor": 400
},
{
"direction": "outbound",
"provider": "plivo",
"callType": "manual",
"destination": "GB",
"ratePerMinuteMinor": 300
}
],
"messages": [
{
"channel": "sms",
"category": "utility",
"country": "IN",
"unit": "segment",
"ratePerMessageMinor": 20
}
]
}destination: nullis the price for every destination. Otherwise it is a country or a number prefix, and the longest match prices a call: a call to a UK mobile (+447…) costs the+447price, any other UK number theGBprice.- A rate of
0is a real, free price. A cell that is missing is a destination or category your plan does not offer. - Money is integer minor units of the plan’s
currencythroughout.