DEV Community: Vlad Zoff

SaaS Billing Models: Subscriptions, Seats, Credits, and Add-ons

Vlad Zoff — Tue, 07 Jul 2026 12:12:24 +0000

Billing is product strategy expressed in code. If your starter only handles a single checkout link, you will rebuild it as soon as pricing changes.

This article breaks down the billing models a SaaS foundation should support.

Flat Subscription

The simplest model is one plan, one recurring price.

Use it when:

The product has a clear single package.
Usage does not vary much across customers.
Support and infrastructure costs are predictable.

Implementation needs:

Checkout session.
Subscription created webhook.
Subscription updated webhook.
Subscription canceled webhook.
Customer portal.
Plan state in the database.

Tiered Plans

Most SaaS products need at least two paid tiers.

Typical differences:

Feature access.
Usage limits.
Support level.
Number of seats.
Data retention.
Integrations.

Store planId in your subscription table and map it to a local plan catalog. Do not rely on provider price IDs as your product logic.

Seat-Based Billing

Seat billing is common for B2B SaaS. It aligns price with customer team size.

You need:

Current seat count.
Optional max seat cap.
Member invite logic.
Checkout or subscription update flow.
Billing UI that explains renewal impact.

Usage Credits

Usage credits work well for AI, API calls, file processing, or metered workflows.

Track:

Total credits.
Used credits.
Reset date.
Usage events.
Budget alerts.
Overage policy.

Credits should be visible to the customer before they become a billing surprise.

Add-ons

Add-ons let you expand revenue without forcing every customer into a higher tier.

Examples:

Extra storage.
White-labeling.
Priority support.
Advanced analytics.
Additional AI credits.
Premium integrations.

Your checkout and subscription state need to support multiple line items, not just one plan.

Trials

Trials are useful when activation requires product usage. They are less useful when setup is complex and a sales conversation is needed.

If you support trials, store:

Trial end date.
Trial status.
Conversion events.
Reminder schedule.
Cancellation behavior.

One-Time Purchases

Some developer products sell lifetime access or source code licenses. That model needs different state than recurring SaaS:

License tier.
Project count.
Update period.
Support period.
Delivery workflow.
Receipt and access email.

Do not mix one-time license logic into recurring subscription code without clear types.

Webhooks Are the Source of Truth

Checkout success pages are not enough. Provider webhooks should update your database.

At minimum, handle:

Checkout completed.
Subscription created.
Subscription updated.
Subscription deleted.
Payment failed.
Refund.

Log webhook delivery and errors. Silent billing failures are expensive.

Admin Billing Support

Your admin panel should show:

User name and email.
Provider.
Plan ID.
Status.
Seat count.
Renewal date.
Cancellation state.

Support should not need direct database access to answer a billing question.

Pick the Model You Can Explain

The best billing model is not the most sophisticated one. It is the one customers understand and your system can enforce.

Start with the simplest model that matches value, but choose a codebase that can add seats, credits, add-ons, and trials when your pricing evolves.

Codapult ships billing adapters for Stripe, LemonSqueezy, and Polar with normalized webhook handling, subscription state in the database, seat tracking, usage credits, and a customer portal — switchable via PAYMENT_PROVIDER without touching application code. The payments docs show the integration points.

Auth, Teams, and RBAC in a Next.js SaaS App

Vlad Zoff — Tue, 07 Jul 2026 12:07:58 +0000

Authentication gets users into the app. Authorization decides what they can do once they are there. In SaaS products, the second part is where many starters are too thin.

This guide covers the practical model: platform roles, organization roles, protected routes, admin access, and future enterprise needs.

Start with the User Record

Keep the user record to identity only — id, name, email, verification state, avatar, platform role, 2FA state, timestamps. Nothing organization-specific belongs here, because the same person can be an owner in one workspace and a viewer in another. The moment you store a permission field directly on the user, you've hard-coded an assumption that breaks the first time someone joins a second organization.

Add Platform Roles

Platform roles are global. Most apps only need:

user.
admin.

The admin role controls platform screens such as /admin/users, /admin/subscriptions, and /admin/feature-flags.

Do not use platform admin for customer workspace permissions.

Add Organization Memberships

Organization roles should answer what a user can do inside one workspace:

owner: billing, members, settings, deletion.
admin: most management actions except ownership transfer.
member: normal product usage.
viewer: read-only access.

This gives you enough granularity without creating a complex permission system too early.

Protect Routes at Multiple Layers

Route protection should happen in more than one place:

Middleware or proxy redirects unauthenticated users.
Layouts block protected app areas.
Server actions verify the session.
API routes verify the session.
Admin operations verify platform role.
Organization operations verify membership and org role.

The UI can hide buttons, but the server must enforce permissions.

Keep Auth Pages Out of Search

Sign-in, sign-up, dashboard, and admin pages should not be indexed. They are not acquisition pages, and search engines do not need them.

Use:

robots metadata with index: false.
robots.txt disallow rules for protected paths.
Sitemap exclusion for auth-only pages.

This keeps SEO focus on marketing, docs, blog, pricing, and comparison pages.

Plan for Enterprise Auth Without Building It Too Early

Enterprise customers often ask for:

SAML SSO.
SCIM provisioning.
Enforced 2FA.
Audit logs.
Domain verification.
Custom session policies.

You do not need to ship every enterprise feature on day one. You do need a data model that can add them without rewriting auth and teams.

Support Impersonation Carefully

Impersonation is powerful for support, but it is sensitive.

Rules:

Only platform admins can impersonate.
Show a visible impersonation banner.
Log the impersonation start and end.
Never let impersonation bypass destructive confirmation steps silently.
Avoid using impersonation for billing provider actions when possible.

Test the Permission Matrix

Write tests for:

Anonymous user access.
Authenticated user access.
Admin-only routes.
Owner-only organization settings.
Member actions.
Viewer restrictions.
Locale-prefixed protected routes.

Auth regressions are high-risk because they often expose data, not just break UI.

The Practical Baseline

None of this is exotic. A real auth provider, protected routes at every layer, a platform admin role, an organization membership table with roles, server-side permission checks, audit logging, and noindex on anything that isn't marketing. That's the baseline that survives contact with a real customer — not an enterprise IAM project, just enough structure that adding SSO later doesn't mean rewriting how permissions work.

Codapult includes this full auth and teams layer out of the box — email/password, OAuth, magic links, TOTP 2FA, SAML SSO, organizations, RBAC, invitations, protected routes and audit logs — switchable between Better-Auth and Kinde via one environment variable. Explore the implementation map in the authentication docs.

Designing Removable Modules in a Next.js SaaS Starter

Vlad Zoff — Tue, 07 Jul 2026 12:03:15 +0000

Most SaaS starters say they are modular.

The useful question is: what happens when you remove a module?

If disabling a feature leaves dead navigation links, broken sitemap entries, missing imports, route handlers that still accept requests, or database tables nobody understands, the module was not really modular. It was just grouped in a folder.

Removable modules need boundaries.

Start With User-Facing Surfaces

A module usually shows up in more places than its main page suggests. Take a waitlist feature: there's the public signup route, sure, but also an admin view, an API route, a database table, an email template, a navbar link, a footer link, a sitemap entry. Delete the public page and the feature is still there — just invisible until someone hits the API route directly or wonders why waitlist_entry is sitting in the schema.

Feature Flags Are Not Enough

Feature flags hide behavior at runtime.

They do not remove code.

That distinction matters. Runtime flags are useful for:

Hiding navigation.
Returning 404 for disabled routes.
Removing sitemap entries.
Preventing API access.
Running one codebase in multiple modes.

But if a buyer wants a smaller codebase, the setup tool also needs to delete files and update references.

A good starter supports both:

Feature flags for runtime control.
Pruning for permanent removal.

Route Groups Help

Next.js App Router route groups are useful for keeping surfaces understandable:

src/app/[locale]/
  (marketing)/
  (auth)/
  (dashboard)/
  admin/

That structure makes it clear which pages are public, protected, authentication-only, or platform admin.

It also lets you reason about SEO. Marketing pages are indexable. Auth, dashboard, and admin pages should be noindex and blocked where appropriate.

Keep Shared Code Honest

The hardest modules to remove are the ones that leak into shared files.

Common leak points:

navigation.ts.
sitemap.ts.
robots.ts.
proxy.ts.
Shared schema files.
Shared validation schemas.
Shared server actions.
Shared dashboard layouts.

If a module needs entries in those files, make the entries obvious and grouped. If a setup wizard removes the module, it should know exactly what to prune.

API Routes Need Gates Too

Disabled UI is not security.

If a module has API routes, those routes need their own gates:

Auth check.
Permission check.
Rate limit.
Feature flag check.
Input validation.

The proxy can return 404 for disabled feature routes, but route handlers should still follow the same protected pattern. That keeps modules safe when moved, copied, or extended.

Database Tables Should Be Named by Domain

Module data should be easy to identify.

Good table names:

waitlist_entry.
feature_request.
audit_log.
outgoing_webhook.
workflow.

Ambiguous table names make removal riskier. If the table name tells you the module, migration work is easier to review.

Tests Should Prove Removal Boundaries

Useful tests include:

Disabled feature returns 404.
Disabled feature is absent from sitemap.
Disabled feature is absent from navigation.
API route rejects unauthenticated access.
Module-specific queries still work when enabled.

You do not need massive coverage for every module. You need enough tests to prevent obvious leaks.

Plugins Are for Bigger Boundaries

Not every removable feature should be a plugin.

A simple waitlist page can be a module.

A CRM with pages, routes, hooks, schema, components, AI helpers, and install commands is a better plugin candidate.

Use plugins when the feature has its own lifecycle and customer value. Use modules when the feature is part of the core application shape.

None of this needs to be exhaustive. It needs to be enough that "modular" describes the codebase instead of describing the marketing copy.

The Payoff

Removable modules give buyers confidence.

They can start broad, then strip what they do not need. Or they can keep a larger operational surface without building it themselves.

The codebase stays understandable because module boundaries are explicit.

Codapult documents removable features in the modules overview, including routes, dependencies, and manual removal notes.

Turso + Drizzle vs PostgreSQL + Prisma for a SaaS Boilerplate

Vlad Zoff — Tue, 07 Jul 2026 12:01:23 +0000

Database choices in SaaS starters are more emotional than they should be.

Turso, PostgreSQL, Drizzle, Prisma, Supabase, Neon, and SQLite all have real strengths. The right choice depends on what the starter optimizes for: local setup, operational familiarity, edge reads, schema control, ecosystem, or enterprise expectations.

This is not a purity argument. It is a trade-off map.

Turso + Drizzle

Turso is hosted libSQL, a SQLite-compatible database with cloud features. Drizzle is a lightweight TypeScript ORM with explicit schema definitions and SQL-like query builders.

The appeal:

Simple local development with file:local.db.
Fast setup for new projects.
Lightweight query layer.
TypeScript-first schema and query types.
Good fit for many SaaS workloads that do not need heavyweight relational operations on day one.
Multi-region read replica story through Turso.

The cost:

Some teams are less familiar with SQLite/libSQL in production.
PostgreSQL has a larger ecosystem.
Enterprise buyers may ask for Postgres by default.
Some third-party tools assume Postgres.

Turso + Drizzle is a strong default when you value small setup and explicit TypeScript code.

PostgreSQL + Prisma

PostgreSQL is the familiar production default for many SaaS teams. Prisma is widely adopted and has a comfortable schema/client workflow.

The appeal:

Very familiar to engineering teams.
Huge hosting ecosystem: Neon, Supabase, RDS, Railway, Render, Fly, and more.
Strong relational feature set.
Many analytics, BI, and integration tools support it directly.
Prisma has excellent discoverability and a large community.

The cost:

Prisma can add more abstraction than some TypeScript teams want.
Generated clients and migrations introduce their own workflow.
Local setup can be heavier than an SQLite file.
Switching away from Prisma later is rarely free.

PostgreSQL + Prisma is a strong default when team familiarity and ecosystem matter more than minimal setup.

PostgreSQL + Drizzle

This middle path is increasingly attractive precisely because it refuses to pick a side: you get PostgreSQL's familiar hosting story and Drizzle's thinner query layer. The trade-off is that you still need a real Postgres instance for local dev — no single-file convenience — and Drizzle's ecosystem, while growing, is smaller than Prisma's. For teams that think in SQL, this is often the most pragmatic option on the table.

What a SaaS Starter Should Do

A starter should make the default easy without pretending it is universal.

The docs should answer:

What database is default?
How do I run locally without a cloud account?
How do migrations work before and after production data exists?
Can I use PostgreSQL?
If PostgreSQL is supported, which env vars change?
Which schema file is the source of truth?
What are the trade-offs?

The worst answer is silence. Buyers interpret silence as lock-in.

Migration Workflow Matters

For a fresh database, db:push is convenient.

For production data, generated migrations are safer.

That distinction should be explicit:

# Fresh local database
pnpm db:push

# Production changes
pnpm db:generate
pnpm db:migrate

Most SaaS teams can start fast and become stricter when real data appears.

Query Code Should Stay Boring

Regardless of provider, application code should import one database client:

import { db } from '@/lib/db';

The app should not know whether the active provider is Turso or PostgreSQL. Provider selection belongs in database initialization, not in every route handler.

That boundary matters more than the default.

The Practical Recommendation

If fast local setup and multi-region reads matter most, start with Turso + Drizzle. If your team already knows Postgres, or your customers expect it, use Postgres — with Prisma if you want the generated-client ergonomics, or Drizzle if you'd rather write something closer to SQL. None of these is objectively correct. The mature answer isn't "this database is best" — it's picking a sensible default and documenting the escape hatch.

Codapult defaults to Turso + Drizzle and documents PostgreSQL via DB_PROVIDER=postgres; the database docs cover setup and migration paths.

The Payment Adapter Pattern in Next.js: Stripe, LemonSqueezy, and Polar Without App-Wide Rewrites

Vlad Zoff — Tue, 07 Jul 2026 11:33:39 +0000

Most SaaS apps start with one payment provider.

That is fine. The mistake is letting that provider become the architecture.

If Stripe-specific objects leak into pages, server actions, admin tools, and webhook handlers, switching to LemonSqueezy or Polar becomes a rewrite. Even adding one-time products next to subscriptions can become awkward.

The payment adapter pattern keeps provider details behind a small interface.

The Shape of the Problem

Payment code tends to sprawl fast: pricing CTAs, authenticated checkout, one-time marketing checkout, billing portal links, webhooks, refunds, seat changes, usage credits. Import a provider SDK directly in even half of these, and every feature becomes provider-aware — which means every provider migration becomes an app-wide grep.

If each layer imports a provider SDK directly, every feature becomes provider-aware.

That makes the code harder to test and harder to change.

A Small Interface Is Enough

You do not need a large abstraction. Start with the operations the app actually performs:

export interface PaymentAdapter {
  createCheckout(params: CheckoutParams): Promise<string>;
  createMarketingCheckout(params: MarketingCheckoutParams): Promise<string>;
  createPortalSession(customerId: string): Promise<string>;
  handleWebhook(payload: string, signature: string): Promise<WebhookResult>;
  refundPayment(params: RefundParams): Promise<RefundResult>;
}

The rest of the app imports getPaymentAdapter() instead of stripe, lemonsqueezy, or polar.

const adapter = await getPaymentAdapter();
const checkoutUrl = await adapter.createCheckout({
  planId: 'pro',
  interval: 'monthly',
  seats: 5,
  customerId,
});

That one boundary gives you room to change providers without changing every caller.

Keep Plans Provider-Neutral

Plan definitions should describe your product, not your provider.

export const plans = [
  {
    id: 'pro',
    name: 'Pro',
    price: { monthly: 19, yearly: 190 },
    limits: { projects: 'unlimited', aiCredits: 5000 },
  },
] as const;

Provider-specific IDs belong in environment variables or provider mapping code:

PAYMENT_PROVIDER="stripe"
STRIPE_PRICE_PRO_MONTHLY="price_..."

# or
PAYMENT_PROVIDER="polar"
CHECKOUT_VARIANT_PRO="..."

This lets the app reason about pro while the adapter handles provider IDs.

Marketing Checkout Is Different

Authenticated SaaS checkout usually attaches a customer, organization, subscription, and return URL.

Marketing checkout may sell source-code licenses or plugins before the buyer has an account.

That path needs its own method:

await adapter.createMarketingCheckout({
  productKey: 'plugin-ai-kit',
  successUrl,
  cancelUrl,
});

The pricing page can route to /api/checkout?product=plugin-ai-kit, and the route can call the active adapter.

If you prefer direct hosted checkout URLs, keep those as the simpler path:

CHECKOUT_URL_PLUGIN_AI_KIT="https://provider.example/buy/plugin-ai-kit"

In Codapult, CHECKOUT_VARIANT_* wins over CHECKOUT_URL_*, so API checkout is used when a provider variant exists and direct links remain available as fallback.

Webhooks Need Normalized Events

Provider webhooks are not interchangeable.

Stripe, LemonSqueezy, and Polar use different event names, payload shapes, signature headers, and product identifiers. The adapter should normalize those into app-level events.

type WebhookResult =
  | { type: 'subscription.updated'; subscriptionId: string; customerId: string }
  | { type: 'subscription.deleted'; subscriptionId: string }
  | { type: 'payment.refunded'; paymentId: string }
  | { type: 'ignored' };

The route validates rate limits and signature, then passes the normalized result to application code.

What Not to Abstract

Do not hide every provider feature.

Stripe Connect, LemonSqueezy licensing, and Polar's Merchant of Record model are not identical. If you need a provider-specific feature, keep it explicit at the edge of the adapter.

Good adapters remove duplication. Bad adapters pretend different products are the same.

The Payoff

With this boundary in place, pages don't import provider SDKs, webhook routes normalize events before they hit application code, and tests mock one interface instead of three. Switching providers becomes a config change and an adapter update — not a rewrite.

Codapult includes Stripe, LemonSqueezy, and Polar payment adapters; the payments docs show the provider switch and checkout paths.