Stripe Billing & Feature Gating
Relevant source files
The following files were used as context for generating this wiki page:
Stripe Billing and Feature Gating in KudosWall is a multi-tiered system designed to enforce usage limits and provide tiered access to premium features based on a user's subscription status. The system integrates Stripe for payment processing, subscription lifecycle management, and checkout sessions, while utilizing internal logic to gate features such as video testimonials, custom domains, and workspace limits.
The architecture ensures that billing states are synchronized across the database and external marketing tools like Loops.so, allowing the application to react in real-time to plan changes, successful checkouts, and webhooks.
Sources: README.md:57-58, loops-email-collection.md:9-16
Architecture and Data Flow
The billing system follows a decoupled monorepo architecture where the web application handles the UI for settings and checkouts, while the @my-better-t-app/stripe package manages the core integration logic.
Subscription Lifecycle Flow
When a user initiates a plan upgrade, the system generates a Stripe Checkout session. Upon completion, Stripe sends a webhook to the application, which updates the internal database and triggers synchronization with marketing platforms.
Plan Configurations and Limits
KudosWall defines multiple tiers: Free, Pro (Starter/Brand), Agency, and Lifetime (LTD). These tiers are configured with specific limits on the number of testimonials, projects, and available features.
Feature Matrix
| Feature | Free Tier | Pro (Brand) | Agency |
|---|---|---|---|
| Testimonial Limit | 50 (Text + Video) | Higher/Unlimited | Unlimited (5 Workspaces) |
| Video Recording | Included | Included | Included |
| Badge Removal | No (KudosWall Logo) | Yes (White-label) | Yes (White-label) |
| Custom Domains | No | Yes | Yes |
| Tag Filtering | No | Yes | Yes |
| Team Invites | No | Available | Available |
Sources: apps/web/src/lib/comparisons.tsx:432-466, apps/web/src/app/dashboard/settings/settings-page.tsx:501-525, apps/web/src/components/vs-competitor-template.tsx:120-135
Implementation Details
Feature Gating Logic
The application enforces gating at both the UI and API levels. In the dashboard settings, certain fields (like Custom Redirect URLs) are disabled for users on the Free tier.
// Example of UI Gating in settings-page.tsx
<label className="flex items-center gap-2 text-[11px] font-bold tracking-widest text-neutral-400 uppercase">
Custom Redirect URL
{billing?.plan === "free" && <Lock className="size-3" />}
</label>
<input
disabled={billing?.plan === "free"}
placeholder={billing?.plan === "free" ? "Available on Pro plans" : "https://yourwebsite.com/welcome"}
className={`w-full ... ${billing?.plan === "free" ? "cursor-not-allowed opacity-60" : ""}`}
/>
Sources: apps/web/src/app/dashboard/settings/settings-page.tsx:344-361
Billing Management API
The dashboard uses tRPC procedures to interact with the billing system, allowing users to create checkout sessions for upgrades or portal sessions for subscription management.
billing.createCheckoutSession: Generates a Stripe checkout URL for a specificpriceId.billing.createPortalSession: Generates a URL for the Stripe Customer Portal to view invoices and manage payment methods.
Sources: apps/web/src/app/dashboard/settings/settings-page.tsx:135-153
External Synchronisation
KudosWall integrates with Loops.so to maintain consistent user data for marketing automation. This synchronization includes initializing properties on signup and updating them during billing events.
| Property | Description |
|---|---|
plan | Current subscription tier (e.g., "free", "pro") |
subscriptionStatus | State of the Stripe subscription (active, canceled, etc.) |
projectCount | Number of active projects/workspaces |
testimonialCount | Total testimonials collected |
Sources: loops-email-collection.md:9-16, loops-email-collection.md:44-48
Conclusion
The Stripe Billing & Feature Gating system provides a robust framework for SaaS monetization. By combining high-fidelity UI feedback (locking premium fields) with server-side validation and external event synchronization, the project ensures that usage limits are respected while maintaining a seamless upgrade path for users. The generous 50-testimonial limit on the Free tier serves as a primary activation engine, while advanced features like white-labeling and custom domains drive Pro and Agency conversions.
Sources: apps/web/src/lib/comparisons.tsx:370-385, apps/web/src/app/dashboard/settings/settings-page.tsx:420-435