Stripe Billing

Documentation Index

Fetch the complete documentation index at: https://docs.fim.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

What you get

• Free + Pro tiers with monthly token quotas (defaults: Free 1M / Pro 5M; both tunable post-activation)
• Stripe-hosted Checkout — users upgrade without your code ever touching card data
• Customer Portal — users update payment methods, download invoices, cancel — all on Stripe’s UI
• Webhook-driven lifecycle — subscriptions provision and renew automatically; canceled subs demote to Free at period end
• Quota enforcement — token usage tracked per period; mid-stream cutoff with a structured upgrade prompt
• Admin pages for plan CRUD and subscription monitoring

​

Prerequisites

1. Stripe account with Live mode activated. Singapore-incorporated companies must complete KYC (business UEN, director ID, bank account). Approval typically takes 1-3 days.
2. Stripe Live API key of type Restricted (recommended over Standard sk_live_*** — easier to revoke, scoped permissions).
3. Webhook endpoint publicly reachable at <your-domain>/api/webhooks/stripe.
4. Bank account for payouts. Multi-currency settlement (e.g. USD payout to a USD account) is recommended for non-USD-default Stripe accounts to avoid 1.5-2% FX leakage per transaction.

​

Setup

​

1. Stripe Dashboard

​

Create the Pro product

1. Catalog → Products → + Add product
2. Name: Pro, description: 5M tokens / month, priority support
3. Pricing: Recurring, monthly, $20.00 USD (adjust to your pricing strategy)
4. Save → copy the resulting price_*** ID (you will UPDATE the local billing_plans table with this value after activation)

​

Create a Restricted API key

1. Developers → API keys → + Create restricted key
2. Name: fim-one production
3. Permissions (minimum):
   • Customers: Write
   • Subscriptions: Write
   • Checkout Sessions: Write
   • Customer portal: Write
   • Prices: Read
   • Products: Read
4. Save → copy rk_live_***

​

Register the webhook endpoint

1. Developers → Webhooks → + Add endpoint
2. URL: https://<your-domain>/api/webhooks/stripe
3. Events to receive:
   • checkout.session.completed
   • customer.subscription.created
   • customer.subscription.updated
   • customer.subscription.deleted
   • invoice.payment_succeeded
   • invoice.payment_failed
4. After save, click “Reveal signing secret” → copy whsec_***

​

Configure multi-currency settlement (recommended)

1. Settings → Bank accounts and currencies → Add a settlement currency
2. Pick the price currency (e.g. USD)
3. Attach the matching bank account (e.g. an Aspire USD virtual account)
4. Save — Stripe routes USD charges directly to USD payouts, no FX conversion

​

2. Backend .env

STRIPE_SECRET_KEY=rk_live_***
STRIPE_WEBHOOK_SECRET=whsec_***
STRIPE_BILLING_RETURN_URL=https://<your-domain>/settings?tab=billing

./deploy.sh   # or: docker compose restart fim-one

​

3. Activate in Admin

1. Log in as an admin
2. Admin → System Settings → Billing
3. Toggle Enable Stripe Billing ON
4. The backend validates that both STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET are present — if either is missing it returns 400 and the toggle stays OFF
5. On first activation only, the backend runs an idempotent setup:
   • Seeds Free + Pro plans (skipped if already present)
   • Sets system_settings.default_plan_id to the Free plan id
   • Backfills users.plan_id = free.id for any user without a plan
   • Syncs default_token_quota → Free plan monthly_token_quota so the existing admin-controlled global quota carries over
6. Subsequent toggle off/on is a pure flag flip with no data side effects

​

4. Update the Pro plan with your live price

• Admin → Billing → Plans → Pro → Edit
• Paste your price_1*** (from step 1) into Stripe Price ID
• Save

UPDATE billing_plans
SET stripe_price_id = 'price_1***'
WHERE slug = 'pro';

​

5. Smoke test

1. Open /settings?tab=billing as a regular user
2. Click Switch to Pro
3. Stripe Checkout opens; complete with a low-amount real card (refund afterwards)
4. Webhook should fire — verify in Stripe Dashboard → Webhooks → recent events show 2xx responses
5. Subscription row appears in subscriptions table; users.plan_id flips to pro
6. UI now shows Pro plan + “Manage subscription” button

​

Disabling billing

• All /api/billing/* endpoints return 503
• The webhook endpoint returns 503 (Stripe will retry, then surface in Dashboard as failing — that’s fine, you can disable the webhook in Stripe Dashboard instead if billing is permanently off)
• The Plan & Billing user-facing tab disappears
• The Admin → Billing nav group is hidden
• The quota chain skips the plan tier and falls back to default_token_quota directly

​

Calculation reference — quota & token math

​

Glossary

​

What counts as a token

• Counted: prompt tokens + completion tokens on every model call
• Counted: every round-trip in a multi-step / tool-use agent flow (each model call is its own debit)
• Counted: embedding requests (KB ingestion, retrieval scoring)
• Not counted: input staged but never sent to a model (e.g. uploaded files that the user discards)
• Not counted: requests that fail before reaching the provider (auth error, rate-limit pre-check)
• Cached input: counted at full price in v1 (no provider cache discount is surfaced). v2 may credit cached prompt tokens separately.

​

Three-state override semantics

​

Quota resolution chain — v1 (current)

1. users.token_quota        ── NULL? skip. 0? unlimited. N>0? cap at N.
2. users.plan.monthly_token_quota   ── only when billing_enabled = TRUE
3. system_settings.default_token_quota  ── defensive fallback
4. unlimited                ── last resort if everything above is NULL

​

Period reset

• For paid users, quota_reset_at mirrors Subscription.current_period_end. The invoice.payment_succeeded webhook handler sets tokens_used_this_period = 0 and advances quota_reset_at to the new period end on each successful renewal.
• For Free users (no Stripe subscription), an hourly cron rolls tokens_used_this_period to 0 on a calendar-month boundary anchored to plan-assignment date.
• Plan changes mid-period do not reset the counter — only renewals do. This prevents quota-cycling exploits (“subscribe → use Pro quota → cancel → subscribe again”).

​

Mid-stream enforcement

• Pre-flight check at chat-call entry: cheapest path, blocks requests the user can’t afford to start.
• During streaming, the running token count is re-evaluated on every chunk. Crossing the cap closes the stream with a structured terminator frame, not a network error.
• The frontend interprets the terminator and surfaces <QuotaExceededDialog> with a deep link to /settings?tab=billing.
• Non-streaming responses return HTTP 402 with body { code: "QUOTA_EXCEEDED", reset_at, upgrade_url }.

​

Billing-disabled fallback

• Step 2 of the chain is skipped — the chain collapses to override → default → unlimited.
• /api/billing/* and /api/webhooks/stripe return 503.
• Plan & Billing user tab and Admin → Billing nav group are hidden.
• All billing data (subscriptions, plans, users.plan_id) is preserved — re-enabling resumes from the same state with no migration.

​

Reserved: quota chain v2 — Team seats

• Subscription.quantity carries seat count (Stripe-native).
• A user’s effective plan resolves through Team membership before falling back to their personal plan:
  effective_plan = team.plan if team_member(user) else user.plan
  
• Quota is per seat (each Team member gets a full monthly_token_quota), not a pooled bucket. Pooled buckets create first-come-first-served exhaustion and are anti-customer.
• Override semantics are unchanged — Team admins can still hard-cap individual members via users.token_quota = N, which sits above the team plan in the chain.

​

Reserved: quota chain v3 — native Org allocation (no Stripe)

• New table org_quota_allocations(user_id, monthly_token_quota, org_id) distributes a parent budget across members.
• Allocations are per user, not a shared pool — every member has a clear individual SLA.
• Updated chain:
  override → max(plan_quota, org_allocation) → default → unlimited
  
• max(), not sum(). A paid Pro user never gets less than they paid for, even if their Org admin sets a low allocation. Stripe-paid quota is sacrosanct.

​

Reserved: pay-per-use credit balance (v3 separate dimension)

• New table user_credits(user_id, balance_cents, currency) — funded via Stripe Checkout mode='payment'.
• Consumption order: subscription quota first, then credit balance (only after subscription is exhausted does the credit decrement begin).
• Credit balance is non-refundable (industry standard for prepaid).
• UI exposes both bars: Subscription quota: 4.2M / 5M used + Credits: $7.40 remaining.

​

Default values

​

Pricing model

• Team plan (Stripe seats / subscription.quantity)
• Annual billing
• Multi-currency presentment
• Coupons / promo codes
• Tax handling (Stripe Tax integration — needs separate compliance review)
• Usage-based metering / overage charges
• Pay-per-use credit balance (one-time top-up)

​

Troubleshooting