Billing and subscriptions module

The billing module handles plans, checkout, one-time and lifetime purchases, subscriptions, and the customer portal. It is provider-agnostic with a Stripe-first implementation.

Architecture at a glance

Buyer -> POST /api/v1/subscription/checkout
      -> payment provider layer (selected by PAYMENT_PROVIDER)
          - stripe       -> Stripe Checkout
          - lemonsqueezy -> Lemon Squeezy (one-time/lifetime only)
      -> returns { url } -> client redirects to hosted checkout

Payment completes -> gateway calls our webhook -> verify -> dedup -> provision

Both providers converge on one provider-agnostic money path, so provisioning logic is not duplicated.

Plans

• Manage plans and their Stripe price IDs in the admin panel at /admin/plans.
• A plan's database price ID takes precedence over the STRIPE_PRICE_* env fallback.
• Plans can be monthly, yearly (enabling a Monthly/Yearly toggle on /pricing), or a one-time lifetime package.

One-time and lifetime purchases

• The FastStaq sales site sells a single lifetime package.
• On checkout.session.completed, the webhook grants the entitlement once. Provisioning is idempotent: replaying the same event does not double-grant.

Subscriptions and the customer portal

• Subscription lifecycle events (customer.subscription.updated/deleted, invoice.payment_succeeded/failed) keep the local subscription in sync.
• Plan changes are rate-limited by PLAN_CHANGE_COOLDOWN_MS (default 24h).
• Refunds and disputes (charge.refunded, charge.dispute.created) are handled and can trigger access changes.

Switching providers

Flip PAYMENT_PROVIDER (and the client NEXT_PUBLIC_PAYMENT_PROVIDER) between stripe and lemonsqueezy. All Stripe code stays intact when Lemon Squeezy is active. Recurring subscriptions, the customer portal, and affiliate clawbacks are Stripe-only.

Related articles

• Configure Stripe payments
• Setting up Stripe webhooks (live)
• Credit system module

Still need help?

Open a support ticket with the order or event details.