Skip to main content
Synced from the repo — do not edit here

Canonical source: docs/claude/billing-pricing.md. This page is generated by docs/scripts/sync-handbook.mjs. Edit the source file in the repo; changes appear here on the next build.

Billing & Pricing — Model, System Map & Implementation Plan

Status: model DESIGNED and documented; NOT yet wired into live billing. The current production backend still runs the OLD plans (Practice $99 / Pro $499 / Multi $1,999). Moving to the model below is a production billing migration — see §4 (grandfathering) and §5 (blockers).

The always-loaded summary is in the root CLAUDE.md → "Pricing Model." This doc is the fuller version with the system map + implementation plan.

Strategy = premium cash-cow: charge up front, no free tier, 80% gross-margin target (see ready-practice-strategy-memo.html).

1. The pricing model (source of truth)​

Public offering​

One self-serve plan ($999/mo) or Custom. No public tiers. Custom is sales-led per client via set_custom_billing.

Base plan — $999​

VariableValue
base_monthly$999/mo
base_annual_upfront (first-year signup)$8,495/yr (~29% off, paid upfront) — renews at standard annual $9,995/yr (~17% off)
active_client_cap1,000 (then usage-based / custom)
staff_seatsUnlimited
eprescribe_seats_included1
wearablesIncluded
Atlas AI (text)Pooled monthly allowance → usage-based overage

AI allowances + overage — all [PLACEHOLDER], set from real vendor costs​

ItemIncludedOverage
Atlas AI (pooled text: copilot + doc/lab analysis + client chat)[PLACEHOLDER] (≈ 2,000 copilot Qs or ~300 doc analyses)[PLACEHOLDER] /1K tokens (marked up over Claude cost)
AI Scribe (Recall.ai, per-min)300 min [PLACEHOLDER]$0.12/min [PLACEHOLDER]
AI Call Center (ElevenLabs + Twilio, per-min)60 min [PLACEHOLDER]$0.90/min [PLACEHOLDER]
SMS[PLACEHOLDER]/mo$0.02 /msg (~1.5x Twilio cost; Klaviyo charges $0.009–0.012)

Metering rule (agreed): pool the three text AI categories into ONE allowance (same per-token cost, different volumes) shown with an example-consumption table; meter audio (Scribe, Call Center) separately per-minute (different, higher cost structure). Overflow = auto-overage (AI keeps working, billed past the cap, alert at ~80%) — no hard stop, since Atlas is the core interface.

Add-ons​

Add-onPrice
White-labeled app$4,995 setup + $495/mo · annual-upfront: $2,995 setup + $399/mo (prepaid) · renews at $495/mo, setup one-time
Lab Ordering (LabCorp / Quest / BioReference · home kits · at-home phlebotomy)$495/mo — per-panel fees extra
Medical Provider Network$495/mo + $60–100/consult
Additional e-prescribe seat$99/seat/mo

Usage-based platform fees (revenue ON TOP of subscription; billed monthly as incurred)​

FeeRate
Payment processing platform fee+0.25% of card volume (on top of Stripe 2.9% + $0.30 pass-through)
Insurance billing (RCM, % of net collections, tiered)3.0% ≤$25k · 2.75% $25–100k · 2.5% $100–250k · 2.0% $250k+ · min $300/mo · payer fees at cost

Financing​

Third-party financing (spread monthly, Ready collects upfront) — US clients only, and only when annual contract value > $10k.

Custom / done-for-you​

Bespoke via set_custom_billing. Done-for-you tier: from $25k setup / $100k ACV → "Book a call."

Margin​

Target 80% gross margin/account. COGS = Atlas inference + GCP infra + Terra (future, per connected client) + audio-AI vendor costs (Recall.ai, ElevenLabs, Twilio). Protectors: active_client_cap + AI allowances/overage. Verify real GCP-per-client + per-minute vendor costs — most likely to erode 80%.

2. Existing billing system (already built — we RECONFIGURE, not rebuild)​

Backend: basis-functions/functions/src/functions_ai_billing.py.

  • Plans: BillingPlan enum + PLAN_PRICING / PLAN_INCLUDED_TOKENS / PLAN_OVERAGE_RATES dicts. Current live plans: PRACTICE $99, PRACTICE_PRO $499, MULTI_PRACTICE $1,999, ENTERPRISE_V3 custom (+ deprecated STARTER/PRO/CORE/SOLO/MULTI/etc. kept for back-compat).
  • Stripe: STRIPE_PRICES maps each plan to a real Stripe price ID (price_1THK…) in the Basis master account. Subscriptions, billing portal, checkout setup session, payment webhooks, 14-day grace period → SUSPENDED.
  • Custom pricing: set_custom_billing() writes clinicsv2/{clinicId}/settings/aiBilling with customPricing=true, per-service includedTokens, overageRate, monthlyBaseFee, planDisplayName, canChangePlan=false.
  • Usage/quota: per-request log clinicsv2/{id}/aiUsageLog/{reqId}; monthly aggregate clinicsv2/{id}/aiUsage/{YYYY-MM}; check_quota() enforces; overage billed at model cost / PLAN_OVERAGE_RATES.
  • Add-ons: BillingAddon enum + ADDON_PRICING; add_addon_to_subscription / remove_addon_from_subscription manage Stripe subscription items.

⚠️ The core problem: NO single source of truth​

  • Onboarding (components/signup/PricingTiers.tsx) — hardcodes the plans; never calls the backend.
  • Settings → Billing (app/(main)/settings/page.tsx) — reads plan/usage from backend, but hardcodes add-on prices ($99/$200) and token strings.
  • Backend — the real source, inconsistently read.

This triplication is why pricing drifted. Fix = make all three surfaces render from get_billing_plans().

3. What the current system does NOT cover (new work)​

Cross-link: items 1–2 below (metered usage → Stripe invoice items) ARE the #536 generalized usage-invoicer epic (P1). Verified 2026-07-20: only RCM (rcm_billing_monthly) + the Stripe +0.25% application-fee have a LIVE usage→invoice pipeline; SMS/email/Scribe/Call-Center/AI-token overage are rated-but-never-billed. Build the metering here through #536's one usage_billing_monthly() (RCM is the template), don't duplicate. See [[project_usage_billing_gap]].

  1. Scribe / Call Center per-minute — current meter is per-token; audio minutes are a new usage type.
  2. RCM % and the 0.25% processing fee — not in the AI-billing system at all; these are Stripe application fees on connected-account charges (different mechanism).
  3. New add-ons (Lab Ordering, Provider Network, White-label, e-prescribe seats) need ADDON_PRICING entries + Stripe prices.

4. Implementation plan (approved, sequenced)​

  1. Reconfigure functions_ai_billing.py → add a new plan (proposed enum ready_practice) at $999 + annual, new allowances/overage, new add-ons, new Stripe prices. Keep all old plans (grandfathering).
  2. Single-source-of-truth refactor → onboarding + settings render from get_billing_plans() (delete hardcoded values).
  3. Add new usage types → Scribe/Call-Center per-minute, RCM %, 0.25% processing (metered usage → Stripe usage/invoice items + application fees).
  4. Build the public pricing page from the same data → publish for prospects.
  5. Wire set_custom_billing into the quote flow for bespoke deals.

Grandfathering (HARD RULE — do not break anyone's billing)​

Existing clinics have clinicsv2/{id}/settings/aiBilling.plan pointing at their current plan. Never remove those plans from the enum/pricing, and never repoint an existing clinic's config. The new plan is ADDED; only NEW signups default to it. Existing clinics stay on their current pricing.

5. Blockers before anything deploys​

  • New Stripe products/prices must be created (real IDs) for $999/mo, $9,995/yr (and $8,495 first-year), and each new add-on. Cannot fabricate price_… IDs — a fake one breaks checkout. Either create in the Stripe dashboard and supply IDs, or authorize creation via the Stripe API (live-account mutation).
  • Fill the 5 [PLACEHOLDER]s with real vendor numbers: Claude token cost → pooled allowance size + overage $/1K; Recall.ai → Scribe included min + $/min; ElevenLabs+Twilio → Call Center included min + $/min; SMS included + $/msg.
  • This is live Stripe billing — per the payments-safety rule, confirm before each risky step; nothing deploys without explicit go-ahead.

6. Tools already built (support the sales motion now)​

  • Quote builder — /Users/G/Desktop/ready-practice-quote-builder.html. Interactive per-client estimator: $999 base, monthly vs annual-upfront ($8,495 first-year), add-ons, usage inputs (Stripe revenue → 0.25%, insurance → tiered RCM), metered AI (pooled + Scribe/Call per-minute w/ allowances), white-label (annual drop to $2,995+$399), financing (US + >$10k ACV), "% of revenue" line, and a "Request this offer" button that POSTs to submit_offer_request → Slack #growth. Unlisted; intended for readypractice.com sales follow-ups. Uses generic names (no Terra/MDI/Junction/DoseSpot). Custom-quote round-downs are fine (e.g. a client bundle quoted at $15,950).
  • Worked example (annual + white-label, upfront): $8,495 platform + $2,995 setup + $4,788 (12×$399) = $16,278 due today; renews ~$14,783; + usage. For a client at $60k insurance / $40k cash (assume 80%): RCM $48k×2.75% + processing $32k×0.25% ≈ $1,400/mo → ~$16,800/yr additional.
  • Models/artifacts (Desktop): ready-practice-pricing-sheet.html, ready-practice-arr-model.html ($10M), ready-practice-100m-model.html (platform/GMV), ready-practice-strategy-memo.html.
  • Root CLAUDE.md → "Pricing Model" (always-loaded summary).
  • docs/claude/onboarding-signup-flow.md (the signup flow this pricing plugs into).
  • docs/claude/stripe-payments.md (Stripe integration deep-dive).