Troubleshoot billing and usage
Validation checklist
Before escalating a billing discrepancy, record the workspace, plan, selected usage dates, call or chat ID, approximate event time, expected credit event, actual balance, and relevant Stripe invoice. Do not send complete card details or unrelated customer data.
Common problems
| Symptom | Check |
|---|---|
| Top-up paid but balance unchanged | Confirm Checkout completed for the correct workspace, then allow the signed Stripe webhook to add purchased credits and refresh Billing. |
| Subscription checkout returned but plan is still Free | Wait for checkout confirmation polling and Stripe subscription webhooks. Confirm the Stripe subscription is active or trialing. |
| Trial is unavailable | The workspace has already used its one trial, or Pay As You Go was selected. |
| Upgrade button rejects a plan | Only higher-ranked plans can use the in-place upgrade route. Downgrades require cancellation and later resubscription. |
| Upgrade did not apply | Check the Stripe preview, card authentication, and payment result. Failed payment rolls the upgrade back. |
| Included credits changed unexpectedly | Check for a billing-cycle renewal or tier change; either can reset the included allowance. |
| Purchased credits disappeared | Confirm the active workspace. Purchased credits are workspace-scoped and intentionally survive cancellation. |
| Short call has zero voice credits | Its seconds may be banked on that agent until the accumulator reaches a complete minute. |
| Call cost seems too high | Include prior carryover, the configuration snapshot that ran, and separate SMS or transfer events. |
| Vox says more credits are required than the displayed response cost | Vox reserves a safe upper bound before work and refunds the unused amount after settlement. |
| Usage period total differs from current balance | Current balances and banked seconds are live; period categories are date-filtered ledger totals. |
| Voice calls and tests are locked | After repeated invoice failures, update the payment method and complete payment so Stripe can clear the dunning lock. |
| Incoming call receives busy behavior below the displayed line count | Check active records and current add-ons, then test the known active-call scoping boundary described in the concurrency page. |
| Invoice is missing | The page first searches by workspace subscription, then the owner customer, and returns up to 100 invoices. Confirm you selected the correct workspace. |
Reconcile one period
- Open Settings → Usage and set the exact dates.
- Record Calls, Vox, Tools, and daily totals.
- Open Call Logs and inspect attributed voice and tool ledger events.
- Include asynchronous ledger rows with no call ID.
- Separate credit consumption from Stripe money charges and recurring add-ons.
- Compare top-up or subscription money against the Stripe invoice—not against the usage chart.