Billing & meters

Receptionist plans and included minutes

New standalone Receptionist comes in Starter, Business and Scale. With one Vocapable standard local number, the monthly prices are $49 / $139 / $269; with your own Twilio they are $39 / $109 / $219. They include 250 / 1,000 / 2,000 AI minutes respectively. For new orders, additional AI minutes are $0.09 with managed phone service ($0.05 AI plus $0.04 associated carrier service) and $0.05 AI with your own Twilio account, on every tier. Each company shares its allowance across agents and numbers and has up to 2 / 3 / 5 simultaneous AI calls on shared capacity.

AI-connected time includes listening, silence and tool waits, combines each call’s AI segments, and has one 30-second minimum per positive call. The allowance resets at the confirmed subscription renewal and does not roll over. Billing > Manage billing displays the server’s actual included, consumed, reserved and remaining seconds as minutes, plus period dates. A missing counter stays unavailable rather than estimated.

The first managed standard local number is included; extra numbers cost $3/month. Non-AI incoming time costs $0.025 per started minute and one connected eligible transfer leg costs $0.03 per started minute. The AI portion’s local incoming/streaming cost is bundled and is not charged again. See managed business numbers for split-call examples and exclusions. Your own Twilio continues to bill its carrier costs directly. SMS is not included.

The first included number is funded by the paid subscription. AI overage and extra number rentals require settled prepaid credit. Eligible non-AI incoming and connected transfer usage can use the accepted invoice arrangement. Its carrier spending limit is separate from the AI prepaid spending limit; neither permits unlimited usage.

Changes between new tiers preserve the phone arrangement and take effect at the confirmed renewal after an exact price review. They do not reset the active period’s allowance or credit unused minutes. Existing signed prices stay in force. Outbound subscriptions and attached legacy Receptionist keep their accepted rate cards; they do not acquire the new standalone allowance automatically.

Outbound subscription, AI, attempts and phone service

Engage, Workforce and Sales subscriptions remain $349 / $549 / $1,199 per month with their purchased calling capacity. For new orders, AI usage is $0.05/minute on either term, before applicable volume discounts, and outbound attempts are $0.005 each. Orders accepted under the earlier rate card keep their accepted $0.13/minute month-to-month or $0.09/minute three-year AI rates.

The separately accepted supplied-phone offer adds $3/month per standard US local number and 1.5× actual attributable Twilio usage cost. It combines authenticated call legs, Media Streams and supported recording/storage costs, then rounds up once to a whole cent per final call. No number is included in an outbound plan, and these carrier charges do not replace the subscription, AI charge or attempt fee. BYO carrier costs are paid directly at the carrier’s rates with no Vocapable markup. Existing accepted 2× terms and standalone Receptionist bundles retain their own pricing.

Public managed acquisition and outbound activation are not open. Current managed-number acquisition requires paid Receptionist coverage and incoming qualification; current outbound workflows use a verified BYO account. See managed business numbers for exact offer identity and gates. Platform usage estimates and BYO carrier estimates do not reconstruct a final managed carrier charge; the accepted offer and finalized billing records govern.

Reviewing multiple companies

In Billing, choose This company for the selected company’s plan, invoices, payment details and spend controls. Choose All companies to compare current-period estimates for companies where your account has billing access. Each company still has its own subscription and invoices; this view does not combine bills or payment methods.

The overview groups estimates by currency and shows each company’s billing period. With more companies to load, the displayed amount is a subtotal for the companies shown. An unavailable estimate stays unavailable; it is never counted as zero. Companies without a production subscription are identified separately. Prepaid phone tests and carrier charges are excluded from these estimates.

Use Switch company to manage its billing to choose a company and open its Billing page. Changing companies does not transfer knowledge, results or paid access. The account overview requires browser sign-in; a company API key cannot read other companies’ estimates.

Usage meters

Billable usage for each company rates through its append-only usage_events stream. The customer-facing billing meters below are distinct from internal phone accounting records. Outcomes provide evidence, not an extra billing meter:

Meter	What it counts
`telephony_minutes`	AI-agent call time (outbound calls and AI-answered inbound calls), rated as AI usage
`stt_audio_seconds`	Speech-to-text audio processed
`tts_characters`	Text-to-speech characters synthesized
`llm_prompt_tokens`	LLM prompt tokens
`llm_cached_prompt_tokens`	Cached prompt tokens
`llm_completion_tokens`	LLM completion tokens
`gpu_seconds`	GPU inference time
`sms_segments`	Schema-reserved message segments; campaign SMS is unavailable
`lookup_requests`	Compliance bureau lookups

Dial attempts are deliberately not a meter: per-attempt charges are rated from contact-attempt rows at invoicing time. Read your usage at GET /v1/usage/summary?period=2026-07 and GET /v1/usage/events; invoices at GET /v1/invoices; your plan at GET /v1/subscription.

BYO minutes are your carrier’s line, not ours

For BYO numbers, calling uses your own Twilio account, so your carrier bills your carrier minutes directly and a Vocapable invoice carries no carrier line. telephony_minutes still records the time your AI agent spends on each production call, and is rated under your accepted AI allowance and overage or legacy per-minute rate rather than as carriage. That includes the AI-answered part of an inbound Receptionist call, metered per second with a 30-second minimum per AI-answered call; an answered call carries no per-call fee, and keypress menus, rings to your own people, forwards, spoken messages, voicemail and the human part of a transfer are not AI usage. New managed tiers bundle the AI portion’s local inbound/streaming service and rate non-AI incoming and transfer time separately; legacy managed offers retain their accepted carrier terms; see managed business numbers. LLM tokens are bundled on the internal serving path and metered as a marked-up pass-through only when your agent’s route bursts to external providers.

The compliance floor is never a line item: AI disclosure, internal-DNC suppression, and the kill switches apply on every plan at no charge. On a configured live phone call, an opt-out phrase durably records the contact’s suppression before the call closes; browser and simulated test calls have no contact to suppress. Bureau scrub stages (lookup_requests) are a pass-through at small markup, and a tenant with a signed upstream-scrubbing attestation waives those stages and the pass-through with them, recorded per attempt so the invoice and the evidence export agree on what ran.

Spend caps fail closed

Set a spend cap with PUT /v1/billing/budget (billing:write) and read it back with GET /v1/billing/budget. The platform enforces it at launch and per dial batch, so there is no side door:

spend_cap_exceeded means the period’s cap is spent. The detail names the amount, the cap, the period start, and where the cap came from. Running campaigns are unaffected.
spend_state_unknown means the ledger holds chargeable usage on a meter your plan carries no rate for, so period-to-date spend cannot be established. Unknown spend state does not launch: price the meter or clear the cap.

The usage.threshold webhook event fires at 50%, 80%, and 100% of an included quantity or the spend cap, so wire it to your alerting rather than polling the summary.

Reading and setting the budget

curl https://api.vocapable.com/v1/billing/budget \
  -H "Authorization: Bearer vcp_test_..."

{
  "currency": "USD",
  "balance_minor": 4900,
  "spend_cap_minor": 250000,
  "spend_cap_period": "month",
  "low_balance_threshold_minor": 25000,
  "period_spend_minor": 18240,
  "unpriced_meters": []
}

curl -X PUT https://api.vocapable.com/v1/billing/budget \
  -H "Authorization: Bearer vcp_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "spend_cap_minor": 500000,
    "spend_cap_period": "month",
    "low_balance_threshold_minor": 50000
  }'

GET needs billing:read; PUT needs billing:write. spend_cap_period is day or month; any field sent as null clears that setting. unpriced_meters is what spend_state_unknown is about: while it is non-empty, period-to-date spend cannot be established and launches refuse.

Neither budget route emits RateLimit-* headers today. Honor 429 and Retry-After rather than keying your back-off on the headers alone.

Converting to production

POST /v1/subscription starts an eligible tenant’s production subscription. It takes the workload_class you declared and a term, creates the subscription, and redeems the sandbox credit against it; it does not promote the workspace to live:

curl -X POST https://api.vocapable.com/v1/subscription \
  -H "Authorization: Bearer vcp_test_..." \
  -H "Content-Type: application/json" \
  -d '{"workload_class": "sales", "term": "three_year"}'

The response names the plan, the term, the base price, the session counts, the period, and sandbox_credit_redeemed_minor. Watch sandbox_credit_unconfirmed: when it is present, the subscription exists and the credit redemption did not confirm, so the amount it names is still owed to you and support will apply it - the subscription is not rolled back for it.

workload_class is one of engage, workforce, sales - the class you declared during onboarding, which the screening floor validated. term is mtm or three_year; the term moves the AI-minute rate, never the base fee. A three_year order requires the current 3-Year Commitment Addendum to be accepted first (POST /v1/agreements/accept) - without it the purchase answers agreements_required, naming the outstanding document, and nothing is charged.

extra_sessions is optional (default 0): the quantity of the published extra-concurrent-session add-on to start with, an integer ≥ 0 - never a price, which the catalog owns. On a deployment where the add-on is not yet configured to bill, a non-zero quantity answers extra_sessions_not_purchasable and nothing is created.

The endpoint needs billing:write. It does not accept Idempotency-Key: the server commits one tenant-unique provisioning operation before it calls Stripe. If a provider outcome is unknown, it answers subscription_provisioning_pending and will not submit another order. Wait for the signed Stripe subscription webhook, then refresh GET /v1/subscription; do not change the plan and click again. Once the local mirror exists, another attempt answers subscription_exists.

Extra concurrent sessions

GET /v1/subscription reports extra_sessions (the purchased add-on quantity) and total_sessions (plan.concurrency_limit + extra_sessions - the one entitlement number session admission enforces), and plan.term (mtm or three_year; null on operator-authored plans that predate the vocabulary).

Change the purchased quantity with PUT /v1/subscription/extra-sessions (billing:write). The body carries the absolute target, never a delta - setting 3 twice leaves you with 3 - so an ambiguous outcome cannot double a fee and retrying the same number is always safe:

curl -X PUT https://api.vocapable.com/v1/subscription/extra-sessions \
  -H "Authorization: Bearer vcp_test_..." \
  -H "Content-Type: application/json" \
  -d '{"extra_sessions": 3}'

A definite success answers the full refreshed Subscription DTO. The refusals:

subscription_not_found (404) - no production subscription exists yet.
subscription_inactive (409) - the subscription is not in an active state; nothing changed.
subscription_unmanaged (409) - the subscription carries no Stripe reference (dev-seeded or externally provisioned), so there is no subscription item to change.
extra_sessions_not_purchasable (409) - the add-on has no configured price in this deployment.
extra_sessions_update_failed (502) - Stripe definitively refused the change; the local quantity is unchanged and the detail carries the refusal.
extra_sessions_update_unconfirmed (502) - Stripe did not answer, so the outcome is unknown, not failed: the change may still have applied. The local quantity stays unchanged until the signed subscription webhook reconciles it. Refresh GET /v1/subscription shortly rather than assuming failure; because the quantity is absolute, re-sending the same number is safe.

Sandbox and production

Production call access is checked for the company and the published agent version that will handle the call. Engage covers surveys and reminders; Workforce also covers staffing and recruiting; Sales also covers sales and custom outbound work. A Receptionist-only subscription provides no outbound access. Sharing an account does not share this access.

The API returns service_plan_required when campaign launch/resume or a live contact-bound call is not covered. Open Billing to review a plan upgrade; the portal provides a direct link from this error. Creating or cloning a draft does not purchase service. Queued production calls are checked again before dialing, while verified-own-number testing retains its separate authorization and payment requirements.

Inbound answering requires that company’s paid Receptionist entitlement. New standalone tiers have their accepted 2/3/5 simultaneous-AI limit on shared fleet capacity; legacy subscriptions retain purchased connection quantities. Outbound capacity does not cover incoming calls. Before activating an inbound session, the API checks billing, allowance and funding again and claims the company’s available AI capacity. Missing, unpaid or canceled subscriptions return receptionist_plan_required. A busy receptionist lane returns receptionist_capacity_unavailable. The answering policy normally handles busy capacity earlier by continuing to its next step; direct routes use a finite spoken fallback. An unreadable entitlement does not grant a free connection. Saved connection quantities after cancellation do not indicate active service.

New customers choose a plan and pay before continuing into guided setup. Existing development simulation uses vcp_test_ calls without billable production usage; it does not grant unpaid production service. Real platform test calls to verified numbers follow their separate authorization and payment requirements. Production requires an executed Production Services Order, the accepted service plan, confirmed payment and a verified BYO carrier or an acquired, qualified managed number. When those persisted requirements are complete, the active owner can activate a clean, eligible application. Applications needing review go through staff’s fresh-step-up, dual-control promotion. Both paths require a currently active or trialing subscription with a recognized service class. Unpaid, canceled, and past-due subscriptions must resolve billing before new activation. The activation transaction checks billing again; a previously green readiness screen is not authorization. Existing service dunning grace is separate from this new-activation requirement.

Current published rates live on the pricing page, because the rate card is public so you can price a campaign before the first call, and this site does not duplicate numbers that page owns. Legal terms live at www.vocapable.com/legal.