Billing & Subscriptions

Relevant source files

The following files were used as context for generating this wiki page:

• design-system/HEX-YT-INTEL Design System (1)/api/monetization.js/api/monetization.js)
• web/app/billing/page.tsx
• web/app/pricing/page.tsx
• web/components/billing/billing-dashboard-client.tsx
• design-system/HEX-YT-INTEL Design System (1)/ui_kits/console/complete-monetization-flow.html/ui_kits/console/complete-monetization-flow.html)
• GEMINI.md

The Billing & Subscriptions system in HEX-YT-INTEL manages user access tiers, payment processing via Stripe, and usage-based quotas. It integrates a serverless backend architecture with a frontend dashboard to provide real-time visibility into account status, analysis credits, and historical invoices. The system follows a stateless adapter pattern for API interactions, ensuring data flows securely between the application, the database (Supabase), and the payment provider.

Sources: design-system/HEX-YT-INTEL Design System (1)/api/monetization.js:1-12, web/app/billing/page.tsx:1-15, GEMINI.md:144-150

System Architecture

The monetization architecture is built on a "Hex-Lite" pattern (Ports & Adapters). Stateless adapters handle external communications with Stripe, while Supabase serves as the primary persistence layer for user tiers and usage logs.

Checkout & Webhook Flow

The checkout process initiates a Stripe Checkout session, while a webhook handler listens for asynchronous updates to keep the local database in sync with Stripe's state.

The system utilizes specific Stripe events to manage the subscription lifecycle, including customer.subscription.created, customer.subscription.updated, and charge.succeeded.

Sources: design-system/HEX-YT-INTEL Design System (1)/api/monetization.js:192-230, GEMINI.md:144-160

Tiers & Usage Management

The application enforces a tiered access model (Free, Pro, Enterprise). Usage is tracked via usage_logs in Supabase, specifically counting "analyses" performed by the user within a rolling 30-day window.

Tier Configurations

Tier	Description	Logic Source
Free	Limited syntheses per month (default 3).	web/app/pricing/page.tsx
Pro	Unlimited syntheses, priority support, API access.	web/components/billing/billing-dashboard-client.tsx
Enterprise	Custom limits, SLA guarantees, dedicated infrastructure.	web/app/pricing/page.tsx

Quota Enforcement Logic

The system calculates a usagePercent based on analysesUsed vs analysesLimit.

• Near Limit: ≥ 80% usage triggers a warning state (var(--warn)).
• At Limit: ≥ 100% usage triggers a quota exceeded state (var(--err)).

Sources: web/app/billing/page.tsx:18-50, web/components/billing/billing-dashboard-client.tsx:28-36, web/app/pricing/page.tsx:64-70

API Implementation

The monetization API routes are designed as stateless adapters. They validate inputs such as emails and promo codes before communicating with Stripe.

Key API Endpoints

Endpoint	Method	Purpose	Parameters
/api/prices	GET	Fetches available plans and add-ons from Stripe.	N/A
/api/checkout	POST	Creates a Stripe Checkout session.	email, planPriceId, addonPriceIds[], promoCode
/api/billing-portal	GET	Generates a link to the Stripe Billing Portal.	customerId, returnUrl
/api/gift-card/create	POST	Generates a Stripe coupon with a custom code (e.g., "GC...").	amount, expiresInDays

Code Snippet: Checkout Session Creation

// design-system/HEX-YT-INTEL Design System (1)/api/monetization.js:100-112
const session = await stripe.checkout.sessions.create({
  payment_method_types: ["card"],
  mode: "subscription",
  customer_email: email,
  line_items: lineItems,
  discounts: discounts,
  success_url: successUrl || `${process.env.APP_BASE_URL}/success?session_id={CHECKOUT_SESSION_ID}`,
  cancel_url: cancelUrl || `${process.env.APP_BASE_URL}/billing`,
  metadata: { email, promoCode: promoCode || null },
});

Sources: design-system/HEX-YT-INTEL Design System (1)/api/monetization.js:37-185

User Interface Components

The Billing Dashboard provides a unified view for account administration. It is split into logical sections: Subscription Overview, Usage & Quota, and History.

Dashboard Layout

Components and Data

• BillingDashboardClient: A client-side component that renders the initial billing data fetched from the server. It handles the "Manage in Billing Portal" interaction via a POST request to /api/billing/portal.
• PricingTableClient: Renders plan options (Starter vs Pro) with monthly/yearly intervals.
• OrderSummary: A visual breakdown used during checkout to show subtotal, addon costs, and promo discounts.

Sources: web/components/billing/billing-dashboard-client.tsx:18-50, design-system/HEX-YT-INTEL Design System (1)/ui_kits/console/complete-monetization-flow.html:150-170, web/app/billing/page.tsx:85-110

Data Models (Persistence)

The billing system relies on specific fields within the Supabase users and usage_logs tables.

Field	Table	Type	Description
stripe_customer_id	users	string	The identifier for the user in Stripe's system.
tier	users	enum	'free', 'pro', or 'enterprise'.
analyses_used	users	integer	Counter for the number of syntheses performed.
action	usage_logs	string	The type of action performed (e.g., 'analysis').
created_at	usage_logs	timestamp	When the usage event occurred.

Sources: web/app/billing/page.tsx:21-40, design-system/HEX-YT-INTEL Design System (1)/api/monetization.js:203-207

Conclusion

The Billing & Subscriptions module provides a robust foundation for monetization through its stateless integration with Stripe and usage-tracked tiers in Supabase. By utilizing a "Hex-Lite" architecture, the system remains decoupled from specific payment provider implementations while maintaining strict quota enforcement. The dual-path management—Direct Checkout for acquisition and the Stripe Billing Portal for retention—ensures a seamless user experience for account administration.