AI Credits - Balance, Packs, and Auto Top-Up

Summary

Torqueflow uses an AI credit system to meter usage of AI features across voice calls, WhatsApp, SMS, and diagnostic queries. Each subscription includes a monthly credit allowance. Owners can view their balance, purchase additional credit packs, and configure automatic top-ups. The credit dashboard appears on the Settings > Billing page below the subscription details.

Prerequisites

• You must be signed in with billing.credits.view permission to see the credit dashboard.
• You must have billing.credits.purchase permission to buy credit packs or configure auto top-up.
• Credit pack purchase and auto top-up are only available on active or grandfathered subscriptions.

Steps

View your credit balance

1. Navigate to Settings > Billing.
2. Below the subscription card, find the Credit Balance card with a fuel gauge icon.
3. The card displays:
   • Total balance - a large number showing credits available.
   • Fuel gauge - a colour-coded progress bar:
     • Green: healthy (50%+) or moderate.
     • Orange: low (20-50%) or very low (10-20%).
     • Empty with orange outline: exhausted (0%).
   • Status text below the gauge reads one of: “Credits healthy”, “Credits in good shape”, “Credits running low”, “Credits very low”, or “No credits remaining”.
   • Natural-language estimate - e.g. “Based on your usage, these credits should last approximately 12 days.” If there is not enough usage data, it reads “Not enough usage data for an estimate”.
4. Below the estimate, a credit type breakdown shows:
   • Subscription credits with the refresh date (e.g. “refreshes 1 May”).
   • Purchased credits with “(no expiry)”.
   • Gifted credits with the expiry date if applicable.

View usage by channel

1. Below the credit balance widget, the Usage This Cycle card shows a 4-column grid.
2. Each channel displays an icon, label, interaction count, and credit usage:
   • Voice - number of calls and credits used.
   • WhatsApp - number of messages and credits used.
   • SMS - number of messages and credits used.
   • Diagnostics - number of queries and credits used.
3. Channels with no usage appear dimmed.
4. Note: per-call cost is never shown. The display leads with interaction count, with credits as secondary information.

View credit usage trend

1. The Credit Trend Chart card shows daily credit consumption over time.
2. It includes the current period total, previous period total, and percentage change.

View purchase history

1. The Purchase History section lists past credit pack purchases.
2. Each entry shows the date, pack name, number of credits, cost, and source (manual purchase or auto top-up).

Purchase a credit pack

1. Scroll to the Credit Packs section on the billing page.
2. Available packs display as cards in a grid, each showing:
   • Pack name with a lightning bolt icon.
   • Number of credits (e.g. “1,000 credits”).
   • Price in GBP (e.g. “£10.00”).
   • Per-credit cost (e.g. “1.0p per credit”).
3. If multiple packs are available, the pack with the lowest per-credit cost has a purple “Best Value” badge and a highlighted border.
4. Click Buy Now on your chosen pack. The button changes to “Redirecting…” while the Stripe Checkout session is created.
5. Complete payment in Stripe Checkout.
6. On success, a toast message appears: “Credits purchased successfully! Your balance will update shortly.” The balance refreshes automatically after a few seconds.
7. If you cancel checkout, a toast reads: “Purchase cancelled.”

Trial accounts

1. Trial organisations see a message in the Credit Packs section: “Your trial includes free AI credits. Upgrade to a paid plan to purchase additional credits.”
2. Trial accounts see a simplified credit dashboard showing only the balance widget and estimate (no usage breakdown, trend chart, or purchase history).

Configure auto top-up

1. Scroll to the Auto Top-Up section below Credit Packs.
2. The card shows an Auto Top-Up heading with a toggle switch on the right.
3. If you have no saved payment method, the toggle is disabled and a message reads: “No saved payment method found. Make a credit purchase to save your card.” with a link to scroll to the credit packs section.
4. Toggle the switch to enable auto top-up.
5. Two fields appear:
   • Balance threshold (credits) - enter the credit level that triggers an automatic purchase. The placeholder shows the valid range.
   • Credit pack - select which pack to purchase automatically from the dropdown. Each option shows the pack name, credit count, and price (e.g. “Starter - 1,000 credits (£10.00)”).
6. A cost preview box appears below (e.g. “When your balance drops below 100 credits, we’ll automatically charge £10.00 to your saved card.”).
7. Click Save Configuration.
8. A confirmation dialog appears titled “Enable Auto Top-Up” summarising the charge amount and threshold. Click Confirm to save.
9. A success toast reads: “Auto top-up enabled successfully”.

Disable auto top-up

1. Toggle the Auto Top-Up switch to off. The configuration saves immediately.
2. A toast reads: “Auto top-up disabled”.

Monitor auto top-up activity

1. When auto top-up has been triggered, a line below the card shows “Last auto top-up: 2h ago” (or similar relative time).
2. Monthly statistics appear: e.g. “This month: 3 auto top-ups (£30.00)”.
3. If the last auto top-up failed, a red warning banner appears above the card: “Your last auto top-up failed. Please check your payment method.”

Expected Outcome

• The credit balance dashboard gives a clear view of available credits, usage patterns, and purchase history.
• Credit packs can be purchased via Stripe Checkout. Purchased credits do not expire.
• Auto top-up automatically purchases a chosen credit pack when the balance drops below a set threshold.
• Trial accounts receive free credits and cannot purchase additional packs until they upgrade.

Troubleshooting

Problem	Cause	Fix
Credit dashboard not visible	Missing billing.credits.view permission, or subscription is not active/trial/grandfathered.	Check your role has credit viewing permissions.
”Credit packs are being configured. Check back soon.”	No packs have been set up with Stripe price IDs yet.	Contact Torqueflow support.
Credit pack Buy Now button unresponsive	A purchase is already in progress (double-click protection).	Wait for the current action to complete, then try again.
Auto top-up toggle disabled	No saved payment method on file.	Purchase a credit pack first to save your card details.
”Your last auto top-up failed” banner	Payment method declined or expired.	Update your payment method via Manage Subscription on the billing page.
Balance shows “Balance is being recalculated”	Temporary state while credit ledger entries are refreshed.	Wait a moment and refresh the page.

Notes

• Credit consumption data resets each billing cycle.
• The fuel gauge uses the subscription allowance as its maximum. Purchased and gifted credits can push the total above 100%.
• When credits are exhausted, AI features degrade gracefully rather than stopping entirely.
• The billing page is designed to continue working even if credit data fails to load. You may see the subscription section without the credit dashboard in rare error cases.

Permissions

• billing.credits.view - required to see the credit balance dashboard.
• billing.credits.purchase - required to buy credit packs and configure auto top-up.