Guides

Billing and Usage

The fastest way to get surprised in production is to ignore balance, usage, and failed top-ups until after launch.

Track them from day one.

Pricing

ItemCost
Webhook mode (Zone A: US/Canada)$0.13/min, billed per second
Hosted mode (Zone A: US/Canada)$0.26/min, billed per second
International destinationsZone B = ×2, Zone C = ×3. See Voice zones and SMS zones.
Phone number$2.50/month per number — first number free for 30 days
SMS inboundIncluded worldwide
SMS outbound$0.02/segment (Zone A)
Signup bonus$5 — never expires

Your $5 signup credit covers roughly 38 minutes of webhook calls, 19 minutes of hosted calls, 250 SMS to US/CA, or 2 months of one phone number. Pick whichever combination fits your test plan.

Credits never expire. Saperly does not gift-card-economics your signup grant or any prepaid balance. Whatever you fund stays funded.

You’re charged only for connected call time. International voice is the Zone A rate × the zone multiplier (Zone B = ×2, Zone C = ×3). SMS uses its own zone table — see SMS zones.

Phone numbers are billed $2.50 every 30 days after the line is created — your first number’s first 30 days are free.

Cost examples

Examples below assume Zone A destinations (US/CA); international rates use Zone B (×2) or Zone C (×3) multipliers. For the full destination table, see Voice zones.

ScenarioCost
5-min hosted call (Zone A)$1.30
10-min webhook call (Zone A)$1.30
1 line for 30 days (after free period)$2.50
Startup: 6 numbers + 100 min hosted/month15.00numbers+15.00 numbers + 26.00 voice = $41.00/mo
When your balance hits $0, postpaid auto-charge runs against your saved card to bring you back above zero. If you have no card on file, outbound calls return 402 insufficient_credits. Inbound calls still connect and are billed normally after they complete. Add a card in the portal before going to production.

Check balance

$curl https://saperly.com/api/v1/billing/balance \
>  -H "Authorization: Bearer sk_live_..."

Add funds

Top-ups run through Stripe Checkout from the portal — visit /billing and pick an amount. Programmatic top-up is not exposed at v0.5.3; postpaid auto-charge against your saved card covers the steady-state path.

Review transactions

$curl "https://saperly.com/api/v1/billing/transactions?limit=10" \
>  -H "Authorization: Bearer sk_live_..."

Each transaction in the response looks like this:

1{
2  "id": "txn_abc123",
3  "type": "call_charge",
4  "amount_credits": -130,
5  "balance_after_credits": 870,
6  "description": "5 min hosted call on line_xyz",
7  "reference_id": null,
8  "reference_type": null,
9  "created_at": "2026-04-10T12:00:00Z"
10}
The amount_credits and balance_after_credits fields carry US cents (e.g. -130 means -1.30,870means1.30, 870 means 8.70). The *_credits field names are a v0.5.2.0 carry-over and will be renamed to *_cents in v0.6.x; the values are already cents-honest. The transactions endpoint uses cursor pagination: pass cursor from the previous response and check has_more and next_cursor to paginate.

Track daily usage

$curl "https://saperly.com/api/v1/usage/daily?days=7" \
>  -H "Authorization: Bearer sk_live_..."

Track monthly usage

$curl "https://saperly.com/api/v1/usage/monthly?months=3" \
>  -H "Authorization: Bearer sk_live_..."

Low-balance warnings

Saperly surfaces balance warnings directly in the developer portal so you don’t get caught by a failed call:

  • Below $3 — warning banner on the dashboard, amber pill next to your balance.
  • Below $1 — critical banner, red pill.
  • Below $0 — postpaid auto-charge attempts against your saved card. If no card is on file, outbound calls stop dialing until you add one.

These warnings are in-app only for launch. Email notifications are coming post-launch — until then, poll GET /v1/billing/balance if you need external alerting.

Top up any amount or save a card to clear the banner.

What to alert on

  • low balance
  • unusual call-minute spikes
  • repeated webhook delivery failures
  • high failed outbound call rates

Suggested first dashboard

If you are building your own ops dashboard, start with:

  • balance
  • calls today
  • minutes today
  • SMS inbound and outbound
  • webhook failures
  • last 10 call outcomes

That is enough to catch most operational problems early.

Optimization tips

  • Use webhook mode instead of hosted mode when you can. It’s half the cost (0.13vs0.13 vs 0.26 per minute) because you provide the AI.
  • Keep calls concise by tuning your system_prompt to be direct.
  • Monitor daily usage to catch runaway calls early.
  • Set up balance alerts before going to production.