Trovacast

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.

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.

Read the balance
curl 'https://api.trovacast.com/v1/balance' \
  -H "Authorization: Bearer $TROVACAST_API_KEY"
200 (json)
{
  "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.

October’s calls
curl 'https://api.trovacast.com/v1/usage?from=2026-10-01&to=2026-11-01&channel=voice' \
  -H "Authorization: Bearer $TROVACAST_API_KEY"
200 (json)
{
  "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`
voiceCalls rated, answered or notMinutes 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
smsMessages chargedSegmentsThe destination country
whatsapp, emailMessages chargedMessagesnull
numbers, planLedger entriesFeesnull

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.

October’s statement
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.

Start a ₹1,000 top-up
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"
}'
201 (json)
{
  "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; a pending top-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 at expiresAt, 24 hours) or refunded.
  • checkoutUrl comes 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 answers BILLING_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.

Read the plan’s prices
curl 'https://api.trovacast.com/v1/pricing' \
  -H "Authorization: Bearer $TROVACAST_API_KEY"
200 (json)
{
  "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: null is 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 +447 price, any other UK number the GB price.
  • A rate of 0 is 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 currency throughout.