Guide: billing

Español: Guía: facturación.

What an account can spend, how to see it before it stops dialing, and how to move up a tier. Every read below is a view of data that already exists — never a second source — and the shapes are in the API Reference.

Test keys cost nothing

Simulated calls and SMS of a dd_test_ key are neither metered nor charged. The routes that spend for real answer 403 test_environment to a test key. See the hosted quickstart.

A new account starts inactive

An account created through the public sign-up has a draft plan: anything that spends or places a real call answers 402 plan_inactive until the plan is active. It also starts at the lowest trust level, whose limits are small on purpose.

Know where you stand

Question	Endpoint
Balance, the cap in force, spend against it and the enforcement mode	GET /v1/billing/account
Which spend-alert thresholds have fired	GET /v1/billing/alerts
Invoiceable line items over a window (not the invoice)	GET /v1/billing/summary
Gross cost by campaign, carrier or agent	GET /v1/billing/cost
The wallet ledger, entry by entry	GET /v1/billing/ledger (from, to, entry_type, limit, cursor)
The invoice for one calendar month (period set by the server)	GET /v1/billing/invoice

curl -s $API/v1/billing/account -H "Authorization: Bearer $TOKEN"

A tenant that runs out of balance stops dialing; GET /v1/billing/account is the surface that can say so first. Open holds count as spent, so available_usd errs early. enforcement_mode and the alert thresholds are read-only here: you tune when you are warned, never whether you are blocked. With billing off the answer is 200 with billing_enabled: false and null money.

Move up a tier

curl -s $API/v1/billing/tiers -H "Authorization: Bearer $TOKEN"        # what is on sale, with price and an upgrade flag
curl -s -X POST $API/v1/billing/tier/upgrade \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tier": "<a tier flagged upgrade: true>"}'

• Entitlements move immediately; the price waits for the next period close. This month's invoice does not change by a cent, and there is no proration line.
• Upgrades only. A downgrade, or repeating the call, answers 422 not_an_upgrade; other 422s are unknown_tier, tier_not_sellable and tier_not_in_catalog.
• The price is per seat, per month. GET /v1/billing/tier shows the tier in force and the pending change.
• Takes a dd_ key or an account_admin login; a member login is 403 role_forbidden.

Billing webhooks

There is no billing event in the webhook catalog today. The catalog is closed: call.ended, call.answered, promise.recorded, sms.received, sms.optout, recording.available, disposition.event, carrier.health_changed, anomaly.detected, ai.drift.detected and port_request.ported — an unknown name is 400. To learn about low balance or a crossed threshold, poll GET /v1/billing/account and GET /v1/billing/alerts. How to register, sign and verify any of those events is in Outbound webhooks.

More detail on seats, plans and metering: REST API guide and Rate limits & caps.