SaaS subscription database schema

Subscription state in these kits is a handful of columns on User, not a separate subscriptions table.

plan                 String  @default("free")
stripeCustomerId     String? @unique
stripeSubscriptionId String?

stripeCustomerId is the cus_ id Checkout should reuse. stripeSubscriptionId is the id on customer.subscription.updated. The Stripe Subscription Starter stores them on SQLite. The Complete SaaS Starter Kit stores the same fields on PostgreSQL.

How plan is set

checkout.session.completed sets plan to "pro" and writes both Stripe ids, using metadata.userId. Later, customer.subscription.updated and customer.subscription.deleted set plan to "pro" only when subscription.status is "active" or "trialing". Every other status, including "past_due" and "canceled", sets "free".

That rule is the whole schema. There is no invoice table. Failed charges are discussed in handling failed Stripe payments. The event flow is in synchronizing Stripe subscription state.