Billing & Subscription

Billing & Subscription

1. What it is

The Billing page is where a tenant admin views and manages their organisation’s subscription, payment methods, invoices, and consumable credit balances. It is the single surface for understanding what you are paying, how you are paying, and how much of your consumable resources (SMS, AI tokens, voice minutes) have been used.

• Access: Admin → Billing, or directly at /admin/billing. Requires the Administrator or Super Admin role.
• What it is not: This page does not set pricing or create billing accounts — those are managed by your account team or through the MangoApps Console (system administration). This page is a tenant admin’s view into the billing relationship that already exists.

2. Standing it up

Billing is available to every admin from the moment the organisation exists. The first-time flow is:

1. Go to Admin → Billing. If no billing customer record exists yet, you see a prompt to add a payment method.
2. Click Add Payment Method. This creates a billing customer for your organisation and opens Stripe’s card-entry form. You can add a credit/debit card or a US bank account (ACH).
3. Once a payment method is on file, the Overview tab shows your monthly total, credit balances, and recent invoices. The Contract tab shows your current plan, seat count, and contract period.
4. If your organisation was provisioned by an account manager (the enterprise sales model), the billing customer and subscription already exist — you will see your contract details immediately without adding a payment method.

Silent dependency: a subscription cannot be started without a billing customer. The “Add Payment Method” action creates the billing customer as a side-effect if one does not exist. If you navigate directly to the Contract tab before a billing customer exists, you will see empty state.

3. How it fits together

Billing Customer — the record linking your MangoApps business to Stripe. Each organisation has at most one billing customer, which owns all payment methods, subscriptions, and invoices. It is created automatically when you first add a payment method.

Bundles and Subscriptions — your plan is a bundle (e.g. Essentials, Professional, Enterprise). A bundle determines which apps are included, the support level (email, priority, or dedicated), and the API access level (limited or full). Your organisation holds one platform subscription pointing at a bundle, and optionally additional app-level subscriptions for add-on apps purchased à la carte. Pricing is per seat per month, with a lower rate when billed annually.

Credits — consumable resources (SMS, AI tokens, API calls, voice minutes) tracked via separate credit balances. Each resource type has its own balance with lifetime purchased and lifetime used counters. Credits can come from purchased credit packs or from plan-bundled/promotional credit grants. Grants burn before purchased packs.

AI Usage Policy — a layered enforcement system. The system-admin-set credit cap is the hard ceiling. Below that, the tenant admin can set their own monthly budget (which cannot exceed the cap) and per-user budgets. The policy is enforced at the LLM chokepoint so every AI call checks it. Verdicts are cached for 5 minutes; changes take effect within that window. When the policy cannot compute a verdict (e.g. a database error), it fails open — AI calls are never blocked by a policy-computation failure.

Platform subscription vs app subscriptions — your organisation has one platform subscription (the bundle) and optionally additional per-app subscriptions for add-on apps not included in your bundle. Cancelling the platform subscription triggers cascade-disabling of the bundle’s apps. Cancelling an app subscription only affects that one app.

4. Running it

The billing surface is organised as seven tabs. Each is a distinct admin operation.

Viewing the overview

The default Overview tab at /admin/billing shows summary cards: monthly total cost (with any discount), SMS credit balance, and the five most recent invoices. This is the dashboard view — it does not change anything.

Viewing your contract

The Contract tab shows your current plan, contract period, billing frequency, auto-renewal status, active user count vs licensed seats, and the apps included in your bundle. A usage percentage bar shows how close you are to your licensed seat count. If your subscription was set up through the enterprise sales model, the contract period and account manager details appear here. Admins cannot directly edit the contract — changes go through the account team or the self-serve upgrade flow.

Comparing and changing plans

The subscription page at Admin → Subscription lets you browse available bundles, compare them side-by-side (including which apps each bundle includes), and select a new plan. You can toggle the comparison between monthly and annual billing to see the per-seat rate for each cadence.

• Upgrade — switching to a higher-tier bundle enables the new bundle’s apps for your organisation automatically. The new bundle’s pricing is locked at the time of signup so catalog price changes do not affect you.
• Downgrade — you can choose to downgrade immediately or at the end of the current billing period. A period-end downgrade keeps access to the current bundle’s apps until the period ends, then disables apps that are not in the new bundle (apps shared between bundles stay enabled).
• Trial — bundles may offer a trial period. The default trial length is 14 days but varies by bundle. Trial-ending reminder emails are sent at 7, 3, and 1 days before expiry. You can convert a trial to a paid subscription at any time from the subscription page.

Managing payment methods

Under the Payment tab, you can:

1. Add a card — opens Stripe’s card-entry form. The card is attached to your billing customer and set as default.
2. Add a bank account (ACH) — opens Stripe’s bank-account verification flow. Bank accounts require verification before they are usable.
3. Set a default — click the default button next to any payment method. The default is what gets charged on automatic renewals.
4. Remove a payment method — removes the card or bank account from your billing customer.

Payment methods are either cards or US bank accounts. Bank accounts show a verified/unverified badge.

Viewing and exporting invoices

The Invoices tab lists all invoices with status badges (paid, open, overdue, void). You can:

• Search by invoice number.
• Filter by status (including a dedicated “overdue” filter for open invoices past their due date) and by date range.
• Export to CSV — downloads all filtered invoices.
• View an individual invoice — shows line items, amounts, and a link to the hosted invoice on Stripe.

Invoice amounts are in USD. Overdue invoices trigger a dunning sequence: automated reminder emails at 7, 14, 30, and 45 days past due. The dunning sequence can be paused or cancelled by your account team. It ends automatically when the invoice is paid or voided.

Billing-related emails (invoices, payment receipts, payment failures, renewal reminders, and dunning notices) are sent to the billing customer’s invoice email, falling back to the billing email, and finally to the business contact email.

Managing credits

The Credits tab shows your balance for each resource type (SMS, AI tokens, API calls, voice minutes), recent transactions, and available credit packs for purchase.

• Credit grants — plan-bundled or promotional credits appear here with their expiry dates. Grants burn first (earliest expiry first), then purchased packs, then billed overage.
• Purchase credits — select a resource type and a package. Packages show the credit amount, any bonus credits, and the price.

Managing AI usage and budgets

The AI Tokens tab provides detailed AI usage analytics and budget controls:

• Usage breakdown by provider, model tier, top users, and calling service — with date-range filters (7 days, 30 days, 90 days, 1 year, all time).
• Org monthly budget — set a monthly credit limit for the whole organisation. This is clamped to the platform cap set by your system admin; you cannot exceed it.
• Overage opt-in — controls whether AI usage continues past your included allowance and purchased credits. When opted in, excess usage is post-billed. When opted out, AI calls are blocked once credits are exhausted.
• Per-user budgets — set a default monthly credit limit for all users, with per-user overrides for specific individuals. A blank override falls back to the default.

Changes to limits take effect within 5 minutes (the policy cache TTL). After saving, the cache is explicitly busted so limits often apply within seconds.

Voice AI usage

The Voice AI tab is a read-only view of voice session usage: total sessions, minutes, and cost — broken down by all-time, current month, and today. Voice billing configuration is managed by your system admin, not from this page.

5. Settings

The billing surface itself is largely a view into system-admin-managed configuration. The settings an admin can change directly are the AI usage controls:

Setting	Where	Default	What it changes
AI monthly credit limit	Admin → Billing → AI Tokens	None (unlimited until a cap is set)	Org-wide monthly budget in credits. Cannot exceed the system admin cap. Once reached, AI calls are blocked for the rest of the month.
AI overage opt-in	Admin → Billing → AI Tokens	On	Whether AI usage continues past included allowance + purchased credits. Off = blocked when credits run out.
AI default user credit limit	Admin → Billing → AI Tokens	None (no per-user limit)	Monthly credit budget applied to every user who does not have a per-user override.
AI per-user overrides	Admin → Billing → AI Tokens	Empty	Per-user monthly credit budgets. Blank = falls back to the default.

The system admin controls that the tenant admin cannot change (but whose effects are visible):

• Monthly AI Credit Cap — the hard ceiling set for your organisation. The tenant admin’s monthly budget is clamped to this.
• AI Billing Mode — Monitor (default; meters but does not block on credits) or Enforce credits (blocks when included + granted + purchased credits are exhausted). Set in the Console.

6. More help

• Apps & Licensing — how to enable and configure the apps included in your plan
• Settings Hub — how to find billing and other admin settings
• Ask AI — the assistant answers questions about billing from these articles.