Manage subscription and usage

Use this guide when you administer a team's subscription or need to understand why billing prevents a new call. Plan limits, payment status, channel entitlement and feature availability are different checks: a successful sign-in does not establish that every channel is enabled.

Availability: the My Subscription tab requires an administrator in the selected team context, a selected team and enabled subscription-management and registration UI features. The subscription API requires subscription management and team-admin access for its overview, usage and management operations. Platform-wide readers can inspect permitted API data but do not gain billing-management mutation rights; their Settings tab need not mirror the API's read scope. See Access and teams for role/team diagnosis.

The operator controls FEATURE_SUBSCRIPTION_MANAGEMENT; it is on unless the value is exactly false. The tab additionally depends on FEATURE_REGISTRATION. Hiding registration can therefore hide this tab without disabling the subscription backend. Ask the platform operator when the tab is absent despite the correct team role. Do not disable billing flags as a remedy for an individual team's payment problem.

Open the right team's subscription

1. Select the intended team, then open Settings → My Subscription (/settings/subscription).
2. Check the plan, status, billing-period dates, scheduled changes and any custom-agreement notice before making a change.
3. Compare Current Usage with the plan's allowances. Open Manage Billing for the linked billing customer's payment methods, billing address and invoices.

Read usage and limits

Section or value	What it tells you
Subscription overview	Current plan, status, users, period, overage rates/cap and creation date; scheduled-change and pending-cancellation notices require attention even while the plan is active.
Current Usage — call minutes, AI tokens, SMS	Current subscription-period counters against the plan's included allowance, with calculated overage and cost. Use the displayed period; do not assume every deployment's billing period equals a calendar month.
Usage History	Historical usage records for the subscription; the normal query defaults to 12 months. It is not an invoice ledger.
Available Plans	Active, self-service-selectable plans and their limits; a generated custom-deal plan is not a public catalogue choice. The available catalogue is deployment data, not a fixed list of tiers promised by this guide.
Manage Billing	Opens a Stripe customer-portal session for the linked team. A missing linked customer is a setup problem, not an empty invoice history.

Current-usage cost cards derive amounts from counters and configured rates. They do not prove a payment succeeded. Check billing invoices and subscription status separately. Plan limits also cover resources/capabilities such as team members/admins, API keys, phone numbers and custom LLM keys; having remaining call minutes does not grant those other capabilities.

Set overage and notifications

1. In Subscription Settings, set Overage Spending Cap in EUR. The form converts this to stored cents.
2. Select Notification Thresholds from 30, 50, 70, 80, 90 and 100 percent.
3. Choose Save Settings, wait for success, then reload to verify the saved values.

The validator permits a cap of zero or at least EUR 1, up to EUR 10,000. Zero is not an unlimited-spend setting: the call check treats zero budget as a hard-cap condition when positive included call/token allowances are exhausted. A positive cap also does not create overage pricing where the plan has none.

Changing thresholds resets the per-resource notification trackers, allowing new thresholds to be considered against already-crossed usage. It does not itself demonstrate notification delivery. Use team notifications to review alerts and identify the platform administrator responsible for notification types and recipient configuration. Verify real delivery separately. My Subscription has no action that sends a test notification.

Custom-agreement teams can still change these two settings; doing so does not change the agreement's plan allowances or overage rates. A saved cap increase does not itself clear an already-stored overage-limit lock. If the block remains, ask the operator to inspect the usage/settlement state rather than repeatedly saving or claiming the call restriction has lifted.

Change a self-service plan or billing interval

1. Compare the actual Available Plans, including user/admin, usage and API-key allowances. Check any active commitment and pending change.
2. Under Manage Subscription, use Upgrade Plan or Downgrade Plan, select the target and review the confirmation. The UI groups plans using its configured ranking; do not infer a universal tier order from names.
3. For an interval-only change, use Billing Interval → Monthly / Yearly. This control initiates the change directly; it is not just a preview selector.
4. Recheck the current plan and any scheduled-change notice after success. Verify the billing record when the team is Stripe-linked.

Requested change	Behavior
Ordinary plan upgrade	Applies the new plan and current usage-record limits immediately; linked Stripe changes request immediate prorated invoicing. Usage counters are not reset just because the plan changed.
Ordinary downgrade	Stores a scheduled plan for a subsequent rollover, rather than immediately replacing the current plan. Check the displayed schedule.
Interval-only change with an active commitment	Stores the interval change for after the commitment.
Other ordinary interval-only change	Scheduled for the next billing cycle.
Cancel a pending plan change	Cancel Change clears the scheduled plan/interval and attempts to restore the current Stripe price. It does not cancel the subscription itself.

The UI's Cancel Change action is tied to a scheduled plan object; an interval-only notice can appear without that button. If you need to withdraw an interval-only schedule and no action is shown, contact the platform administrator. Do not interpret a missing button as proof there is no scheduled interval.

After a failed operation, reload before retrying. External billing updates and local state are separate operations, so a failure message alone does not establish that no change occurred. Give support the team and operation, time and displayed state; never send payment credentials.

Cancel, undo cancellation or return after cancellation

State and intent	Action and consequence
Active self-service subscription; stop renewal	Cancel Subscription opens confirmation. Accepted cancellation sets cancellation at period end; it does not immediately mark the subscription fully canceled. An active commitment blocks cancellation.
Cancellation scheduled; keep service	Undo Cancellation clears the scheduled cancellation before full cancellation. This is the UI action backed by reactivation; it is not a new checkout.
Fully canceled self-service subscription	Resubscribe opens the return checkout path. It requires an existing billing customer, an undeleted team and a selectable plan. A fully canceled subscription cannot use Undo Cancellation.
Paused after payment trouble	Update Payment Method opens billing. The resubscribe operation is for canceled subscriptions, not paused subscriptions.

Reload and confirm the expected status after returning from billing. An opened portal or checkout URL is not evidence of payment or restored calling. Do not assume released phone numbers are recovered simply because a new subscription becomes active.

Recover from payment or usage blocks

The pre-call check rejects a missing subscription; CANCELED, PAST_DUE, UNPAID or PAUSED status; an overage-limit lock; an overage-payment failure; or an exhausted positive included minute/token allowance when no overage pricing/budget is available. This describes admission to new calls, not a guarantee that every active call is immediately terminated.

Symptom	Check and responsible person
Payment method or payment failure	Team admin opens Manage Billing/Update Payment Method. Operator checks webhook processing and recorded payment state if recovery does not appear.
Included usage exhausted	Team admin compares allowances and available plans; a zero overage cap is not permission for unlimited extra usage.
Overage spending limit reached after changing the cap	Team admin verifies the saved cap; operator checks the persisted lock and usage/settlement result.
API/SDK, WebRTC or telephone channel denied	Check the active custom agreement's channel entitlements as well as feature flags and permissions; ask the platform admin to correct agreement configuration when appropriate.
Team or old phone number missing after cancellation	Operator checks grace-period expiry, number release and team cleanup before proposing resubscription.

When a subscription invoice fails, the webhook marks the subscription PAUSED and suspends assigned auto-provisioned numbers. The grace-expiry job applies the grace period set by GRACE_PERIOD_DAYS, measured from pausedAt: it can mark the subscription canceled and release those numbers. Grace here is time before cleanup, not a promise that calls continue during payment failure. An overage-invoice failure uses a separate overage-payment-failed flag.

A later canceled-team cleanup job has a default 30-day retention threshold, selecting canceled subscriptions with a sufficiently old canceledAt and a team not yet deleted. It decommissions team access; it is not a promise that all subscriptions are recoverable for exactly 30 days after every cancellation event. The timestamp conditions and scheduled job execution matter. Operators can use background job diagnosis to distinguish waiting, retried and completed cleanup work. Ask the operator for the actual deployment policy before relying on retained data or numbers.

Work with a custom agreement

The overview can show a contract-managed version with its name, commitment, included usage, rates and TEL/WebRTC/API-SDK channels. These are generic product capabilities; this page contains no customer's commercial terms.

A custom-deal association blocks the self-service cancel, undo-cancellation and resubscribe APIs independently of whether its commitment has ended. Standard-plan change is a separate path: a higher-priced standard plan can replace the deal; a non-upgrade is blocked while the deal commitment is active. Leaving the deal through that path clears its association/commitment and applies the target plan's default cap and notification thresholds. Recheck them afterward. Escalate an agreement change to the platform administrator when the intended outcome is not offered by the UI.

Platform administrator: create and apply a version

Availability: Admin Settings → Custom Deals requires the subscription-management feature. Platform readers may inspect deals; writes require platform administrator privileges. Team-admin billing access is not permission to edit custom deals.

1. In Find team, select the exact team and inspect its current version and billing linkage.
2. Fill the proposed terms and choose Save Version. This creates a version and generated hidden plan, and attempts to create its Stripe product/price; saving alone does not activate it.
3. For a team without a linked Stripe customer, use Generate Checkout URL and complete the intended checkout process. The version becomes pending activation; a generated URL is not an active agreement.
4. For a linked existing Stripe subscription, Apply Latest Version applies the version and updates the subscription. This is a billing mutation, not merely marking the draft approved.
5. Verify the active version and the team's subscription overview, cap, thresholds and channel access after activation.

Control group	Meaning
Deal name, Internal notes	Customer-facing display label versus operator context. Keep internal notes free of credentials.
Members, Admins, LLM tokens / month, SMS / month, Call minutes / month, Included phone numbers, API keys	Generated plan allowances; these are separate limits, not a single shared quota.
Term months, Indefinite, Billing frequency	Commitment and billing cadence. Indefinite uses no fixed term; check the saved version rather than assuming the ordinary Monthly/Yearly picker describes every custom interval.
Price per month, overage prices, Additional number / month, Overage cap	Base and extra-usage configuration. LLM overage is labelled per 1000 tokens; do not enter a per-token amount into that field.
Channel choices	At least one channel must be selected by the validator. A channel entitlement does not replace runtime feature/permission checks.
Reset Form	Resets editing inputs; it is not deletion or rollback of saved versions.

Discontinue Custom Deal moves the team back to a standard plan and removes the active deal association; it is not Cancel Subscription. The service uses a selected target when supplied, otherwise the active default selectable plan or the cheapest selectable fallback. Review the resulting plan and limits. Historical versions remain evidence of past configuration; creating another version is the forward-edit workflow.

Review legal documents

Use Settings → My Subscription → Legal Documents to check which document versions the selected team has accepted and review updates. First select the intended team; acceptance records belong to that team, not every team you can access. The tab follows the subscription availability prerequisites.

Team Admin is the ordinary permission for reading the team's consent status and accepting documents. The API also permits platform-wide readers through its team-access guard. Acceptance is an explicit self-service exception for Super Viewer, unlike ordinary billing or resource mutations; this does not guarantee that the Settings tab is visible in every role context. An authenticated session with an unexpired password is required. Ordinary team Members and Viewers cannot use these team-admin operations. See Access and teams.

Control or value	Meaning
Document	Current catalogue document name; an update notice identifies the currently selected version.
Consented Version	Version associated with the team's most recent acceptance for that document type, or Not yet accepted.
Consent Date	Date and accepting person's name when present; dates use the browser's locale. This is not a UTC audit timestamp display.
Downloads → Download	Opens the current catalogue version's file in a new tab. It does not retrieve the previously accepted version merely because that version appears in the neighbouring column.
Review & Accept	Opens the outstanding-document review; opening it does not record acceptance.

1. Compare Consented Version with any new-version notice. Open Download and review the actual file; check its identity and version against the displayed catalogue entry.
2. Choose Review & Accept when updates or unaccepted documents are listed. For each entry, inspect its version, effective date and any Changes text; its Download link opens that current version.
3. Select the individual I have read and agree to… checkbox only for documents you intend to accept for this team. Every displayed outstanding document must be checked before Accept becomes available. Cancel closes the dialog without submitting; reopening resets the checkboxes.
4. Choose Accept once. The button is disabled while acceptance is pending. On success, the dialog closes and the team's status refreshes.
5. Verify the displayed version, date and person after refresh. Redact person names before you share a screenshot of this table. If the catalogue did not change during review, the outstanding notice should clear for the accepted versions. Reopening a file or checking a box alone is not recorded acceptance.

If acceptance fails because a version is no longer active, reload and review the newly displayed documents before retrying. For a permission or password-expiry error, use the account recovery guidance; do not switch to an unrelated team to bypass the error. If the file is missing or differs from the displayed version, stop and ask the platform operator to verify the legal-document catalogue. A hidden/empty card or loading failure is not confirmation that everything is accepted.

The team UI submits all displayed outstanding current versions together. The existing-team API validates distinct active version IDs, but does not independently require the newest complete set; an API success alone is therefore not proof that the team is current. Recheck status. Accepting the same team/version again updates its recorded person and time; it is not an immutable sequence of acceptance events. This handler does not write the optional IP-address/user-agent fields, and consent is linked to a version record rather than a cryptographic hash of downloaded bytes.

Check the outcome

Before closing a billing task, confirm the intended team, active or scheduled plan, billing-period/status, cap/thresholds and any custom-deal association. Test the relevant channel only through your approved test process. If payment and product state disagree, give the operator the time and visible result to reconcile the webhook/job state; do not repeatedly trigger checkout, cancellation or Apply Version blindly.

Related

• Review team notifications — to read usage, overage and payment alerts for the team.
• Understand feature availability — to separate plan entitlements from feature flags and permissions.
• Access and teams — to diagnose the role or team context when the subscription tab is missing.
• Background jobs — to trace grace-period and cleanup jobs after a payment problem.