Skip to content
CallOnline app iconCallOnline Resources
Get API key

Credits, billing readiness, and dynamic pricing

Read /v1/pricing for current rates and packages, use the billing-status endpoint with a billing-scoped key, and confirm available credits, commerce state, spend cap, and compliance readiness before calling.

Updated Aug 20, 2026v1Reviewed by billing and product and engineering

CallOnline pricing is dynamic. Do not copy a displayed rate into application logic or documentation. Read the pricing endpoint when presenting current packages or estimating a workflow.

Dynamic pricing, credit balance, spend cap, and connected usage sequence

Read public pricing

Section titled “Read public pricing”
Terminal window
curl https://callonline.app/v1/pricing

The response is derived from current App9 credit packages and CallOnline rate-card items. Standard and premium voice tiers can have different credits-per-connected-minute values. If the upstream pricing source is unavailable, the endpoint returns an error rather than inventing a current public price.

Check account readiness

Section titled “Check account readiness”
Terminal window
curl https://callonline.app/v1/agent-commerce/billing-status \
  --header "Authorization: Bearer $CALLONLINE_API_KEY"

The key needs callonline.billing or *. The result includes:

  • billingReady, based on a numeric available balance greater than zero;
  • the current creditBalance response;
  • whether agent commerce is enabled;
  • monthlySpendCapCents;
  • whether human approval is required;
  • the commerce kill-switch state;
  • a requiredBeforeCalling checklist.

Use /v1/agent-commerce/usage-balance when you only need the current balance object.

Connected-minute charging

Section titled “Connected-minute charging”

Customer credits are recorded for completed connected usage events, not for a call that never connected. The calculation uses the current tier rate and a 30-second minimum, then rounds the resulting credit amount upward.

Treat this as a billing rule, not a duration guarantee. Carrier events and the pricing source determine the final recorded usage.

Credit holds and reservations

Section titled “Credit holds and reservations”

CallOnline v1 does not expose a public per-call hold resource or a hold identifier. Do not write an integration that waits for an undocumented hold object. The supported public readiness surface is the billing-status response; the supported final usage surface is the account balance and recorded connected-minute charge.

If your own application reserves budget before a call, label it as your application-level reservation and reconcile it after the terminal call state.

Funding flows

Section titled “Funding flows”

GET /v1/agent-commerce/plans lists current fundable plans. POST /v1/agent-commerce/purchase-session creates a human-approved checkout session and requires an idempotency key. Agent-commerce capability endpoints indicate which current or preview payment modes are enabled; never assume a preview mode is available from its name alone.

Purchasing credits does not bypass API scope, calling policy, disclosure, DNC, or quiet-hour checks.

Pre-call checklist

Section titled “Pre-call checklist”
  1. Fetch current pricing if showing an estimate.
  2. Confirm billingReady and a positive available balance.
  3. Check your own approved budget and the returned monthly spend cap.
  4. Confirm the key has callonline.calls for the actual call.
  5. Validate all compliance fields.
  6. Require human approval for the first live workflow and any purchase session.

Avoid automatic funding or calling loops. A billing failure, compliance block, or ambiguous create response should stop the workflow for inspection.