Integrate Clerk org billing for subscription management

[jeevanpillay]

Overview

Integrate Clerk's organization billing feature to handle subscription management for Lightfast orgs. Clerk Billing is a subscription management layer on top of Stripe — Clerk owns plans, subscriptions, and entitlements while Stripe handles payment processing.

Why Clerk Billing

• Orgs already live entirely in Clerk (no org table in our DB) — billing attaches directly with zero schema migration
• @vendor/clerk already exports PricingTable, billing webhook types, and clerkClient for backend queries
• auth().has() already used for role checks — same API supports has({ plan }) and has({ feature }) for plan gating
• <OrganizationProfile /> gains a built-in Billing tab automatically when billing is enabled
• Cost: 0.7% per transaction (Clerk) + standard Stripe fees — no monthly add-on

Plan Structure

Map the existing pricing tiers to Clerk plans:

Plan	Price	Key Limits
Starter	Free	3 users, 2 sources, 2,500 searches/mo, 14-day retention
Team	$20/user/mo	5 sources, 1,500 searches/user, 60-day retention
Business	Contact sales	Unlimited, SSO/SAML, SLA, 1-year retention

Scope

Clerk Dashboard Setup

• Enable Billing in Clerk Dashboard
• Connect Stripe account (separate for dev and prod)
• Create Starter, Team, and Business plans with seat limits
• Define Features mapped to Lightfast capabilities (e.g., search, semantic_search, identity_tracking, sso)
• Create Custom Permissions linked to Features (e.g., org:semantic_search:read)

Codebase Changes

• Replace static pricing page (apps/www) with <PricingTable for="organization" /> or custom UI via usePlans() hook
• Implement Clerk webhook handler for subscription.*, subscriptionItem.*, paymentAttempt.* events (also handle pending organization.* events)
• Add has({ plan }) / has({ feature }) gating in org-scoped procedures and UI where access control is needed
• Wire billing.plan in prompt engine to actual org subscription (currently hardcoded to "free")
• Add billing/plan management to org settings (or rely on <OrganizationProfile /> Billing tab)
• Invalidate membership cache on billing webhook events

Testing

• Verify Clerk sandbox Stripe gateway works in development (zero-config)
• Test plan subscription, upgrade, downgrade, and cancellation flows
• Test feature gating with has() across server and client
• Verify webhook delivery and handling

Known Limitations

These are current Clerk Billing constraints (Beta) that affect our pricing model:

• No usage-based/metered billing — Team plan's per-search quotas and overage charges can't be enforced through Clerk yet ("coming soon")
• No paid add-ons — +$10/source, +$20/mo extended retention not modelable yet ("coming soon")
• USD only — multi-currency on roadmap
• No tax/VAT support — planned
• No 3D Secure / SCA — users with cards requiring additional auth can't checkout
• No coupons/discounts — "coming soon"
• Seat limits are immutable after plan creation
• Clerk is not Merchant of Record — we handle compliance

Dependencies

• @clerk/nextjs 7.0.1 (already installed, meets minimum 7.0.8 for seat limits — verify)
• Stripe account(s)
• Clerk Dashboard billing configuration

References

• Clerk B2B Billing Guide
• Clerk Billing Overview
• Clerk PricingTable Component
• Clerk Billing Webhooks
• Clerk Seat Limit Plans
• Clerk Cached Pricing Table Example