Subscriptions & Stripe Billing

Relevant source files

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

• apps/api/src/services/stripe.service.ts
• apps/api/src/routes/webhooks.ts
• AGENTS.md
• DATABASE_LAYER_COMPLETE.md
• SWEEPBOT_DASHBOARD.html
• PR_REVIEW_EXECUTIVE_SUMMARY.md

Introduction

SweepBot utilizes Stripe as its primary payment processor to manage a multi-tiered SaaS subscription model. The system provides subscription billing with affiliate revenue sharing, allowing users to access different levels of platform features—such as increased platform limits and advanced automation—based on their chosen tier. The architecture integrates Stripe Checkout for initial acquisitions and the Stripe Billing Portal for self-service subscription management.

The billing system is deeply integrated with the API Layer, utilizing webhooks to synchronize Stripe subscription states with the internal PostgreSQL database. This ensures that user permissions and feature gates are enforced in real-time based on the user's active subscription status.

Sources: AGENTS.md:20-22, AGENTS.md:58, SWEEPBOT_DASHBOARD.html:436-440

Subscription Architecture & Tiers

SweepBot implements six distinct subscription tiers, offered across two billing cycles (monthly and annual). Tiers are enforced at the API level via the requireAuth hook, which reads the user's tier from metadata to gate specific features like platform connections.

Feature Gates by Tier

Tier	Platform Limit	Advanced Features
Free	2 Platforms	Basic Tracking
Starter	8 Platforms	Standard Analytics
Pro	Unlimited	Advanced Analytics, Flows
Analyst	Unlimited	Data Export, Advanced Flows
Elite	Unlimited	Priority Support, Full Suite

Sources: SWEEPBOT_DASHBOARD.html:266-267, SWEEPBOT_DASHBOARD.html:436-440, SWEEPBOT_DASHBOARD.html:565-568

Billing Lifecycle Flow

The following diagram illustrates the flow from initial checkout to subscription maintenance via the Stripe webhook.

The system uses mode: payment for lifetime tiers and mode: subscription for recurring cycles. Sources: SWEEPBOT_DASHBOARD.html:436-440, SWEEPBOT_DASHBOARD.html:496-498

Implementation Details

API Endpoints

The subscription logic is primarily handled through the /user and /webhooks routes within the Fastify API.

Endpoint	Method	Purpose
/user/checkout	POST	Generates a Stripe Checkout session URL based on tier and cycle.
/user/billing-portal	GET	Generates a redirect URL to the Stripe Customer Portal.
/user/subscription	GET	Fetches the current user's active plan and status.
/webhooks/stripe	POST	Handles asynchronous events from Stripe (e.g., successful payment).

Sources: SWEEPBOT_DASHBOARD.html:260-262, SWEEPBOT_DASHBOARD.html:436-440

Database Schema

Subscription data is persisted in a dedicated subscriptions table, which is linked to the profiles table. A handle_new_profile() trigger automatically creates a subscription row upon profile creation.

Webhook Handling Logic

The webhook handler at apps/api/src/routes/webhooks.ts is responsible for processing four primary Stripe event types:

1. checkout.session.completed: Initial subscription activation.
2. customer.subscription.updated: Handling renewals or tier upgrades/downgrades.
3. customer.subscription.deleted: Handling cancellations.
4. invoice.payment_failed: Triggering notifications for failed billing attempts.

Crtically, the system uses stripe.webhooks.constructEvent() to verify signatures using the STRIPE_WEBHOOK_SECRET.

Sources: SWEEPBOT_DASHBOARD.html:438-440, SWEEPBOT_DASHBOARD.html:518-522, PR_REVIEW_EXECUTIVE_SUMMARY.md:27-28

Technical Debt & Considerations

As of the current development phase, several critical items have been identified for the billing system:

• Env Var Mismatch: There is a known naming discrepancy where env.ts defines STRIPE_PRICE_*_ANNUAL while routes may reference YEARLY, potentially causing checkout failures.
• Tier Synchronization: Tier enforcement currently relies on user_metadata in the Supabase JWT. If the subscriptions table is updated via webhook without a corresponding update to user_metadata, the user's active permissions may drift until re-authentication.
• Idempotency: The webhook handler currently lacks event ID deduplication, which could lead to duplicate processing if Stripe retries an event.

Sources: SWEEPBOT_DASHBOARD.html:518-522, SWEEPBOT_DASHBOARD.html:543-545, PR_REVIEW_EXECUTIVE_SUMMARY.md:21-25

Conclusion

The Subscriptions & Stripe Billing system provides the commercial backbone for SweepBot, enabling a scalable SaaS model. By leveraging Stripe's hosted UI for Checkouts and Portals, the project maintains a secure payment environment while using Webhooks to ensure the local database and user permissions remain synchronized with external payment states. Implementing the identified fixes for tier synchronization and environment variable consistency remains a high priority for production readiness.