Stripe Billing & Usage Tracking
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Stripe Billing & Usage Tracking system in Comply-Quick manages the lifecycle of user subscriptions, marketplace transactions, and metered API usage. It integrates Stripe's payment infrastructure with a Supabase backend to enforce feature entitlements based on three primary tiers: Pro, Agency, and Enterprise.
The system handles both flat-rate recurring subscriptions (monthly or annual) and consumption-based billing for API calls and scan overages. It utilizes a robust webhook listener to synchronize payment events—such as successful checkouts, subscription updates, and payment failures—with the application's internal database state.
Sources: src/app/page.tsx:206-277, src/app/api/webhooks/stripe/route.ts:133-219
Subscription Architecture & Tier Management
The project defines a structured pricing model where different tiers unlock specific platform capabilities. Tiers are enforced server-side and reflected in the UI via the Command Center and Dashboard Wizard.
Pricing Tiers
| Tier | Billing Options | Key Features |
|---|---|---|
| Pro | Monthly / Annual | 50 scans/mo, Contract shield, Markdown download |
| Agency | Monthly / Annual | 200 scans/mo, Team seats, White-label exports |
| Enterprise | Monthly / Annual | Unlimited scans, HIPAA/PCI-DSS modules, REST API |
Sources: src/app/page.tsx:210-277, src/app/dashboard/DashboardWizard.tsx:109-136
Entitlement Flow
When a user completes a Stripe Checkout session, the application processes a checkout.session.completed webhook. This event triggers the setEntitlement function, which maps the Stripe customer to a Supabase user and updates the subscriptions table with the corresponding tier and status.
Metered Usage & API Billing
Comply-Quick implements consumption-based billing for developer features and scan overages. Usage is tracked in internal ledgers and reported to Stripe for billing at the end of the period.
Metered Components
The system tracks three specific meters:
- api_call: $0.01 per request.
- api_template_upload: $50.00 per programmatic upload.
- extra_scan: $5.00 per scan exceeding the plan limit.
Sources: src/app/dashboard/api/ApiView.tsx:12-16, src/lib/api/stripe-metered.ts:18-22
Usage Tracking Data Model
Metered usage is stored in two primary tables before being synchronized with Stripe.
Reporting to Stripe
Usage is reported via the reportMeteredUsage function. This function iterates through unreported rows in api_usage_meters and billing_overages, calling Stripe's billing.meterEvents.create API. To ensure idempotency, each successfully reported row is stamped with a reported_to_stripe_at timestamp.
Sources: src/lib/api/stripe-metered.ts:51-105
Partner & Marketplace Transactions
The Stripe integration also supports multi-party payment flows for the Partner Program and the Creator Marketplace.
Recurring Referral Commissions
Partners earn a 30% recurring commission on referred customer subscriptions. The webhook listener monitors invoice.payment_succeeded events and triggers accruedReferralCommission. This logic calculates the commission based on the amount_paid and records it in the partner ledger.
Sources: src/app/api/webhooks/stripe/route.ts:68-94, src/app/dashboard/partners/PartnerView.tsx:102-105
Marketplace Settlements
When a template is purchased in the marketplace, the settleMarketplacePurchase function is called. This function:
- Updates the
marketplace_purchasesstatus topaid. - Increments the
sales_countfor the template via an atomic RPC call.
Sources: src/app/api/webhooks/stripe/route.ts:25-44
Error Handling & Revenue Alerts
The webhook route includes specialized handlers for failed payments to protect revenue and alert administrators.
| Event Type | Logic Performed |
|---|---|
invoice.payment_failed | Updates subscription status to past_due and sends a revenue alert. |
charge.failed | Logs the failure reason and sends a detailed revenue alert. |
customer.subscription.deleted | Reverts the user to the free tier and logs an analytics event. |
Sources: src/app/api/webhooks/stripe/route.ts:193-241
Summary
The Stripe Billing & Usage Tracking system provides a unified interface for managing diverse revenue streams within Comply-Quick. By combining flat-rate subscriptions with metered API billing and marketplace settlements, the architecture supports scalable growth while ensuring that feature access is strictly tied to payment status through atomic database updates and robust webhook processing.