Subscription billing

Skill param087/saas-starter-skills/skills/subscription-billing

Production-grade full-stack SaaS skills for AI coding agents — Next.js, Postgres/Drizzle, Auth, Stripe & Vercel patterns for Codex, Claude Code, Cursor & OpenCode.

Install

npx -y skills add param087/saas-starter-skills --skill subscription-billing

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Use when turning payment state into product behavior — model plans and subscription status in the DB, enforce plan limits and feature entitlements server-side, and gate features with a single typed check.

SKILL.md

3.1 KB, as published. Nobody here has run it

Subscription & Billing Logic

Overview

Once payments-stripe syncs subscription state into your database, you need to turn that state into behavior: which features are unlocked, which limits apply, what happens when a plan lapses. Model plans as data, store the org's current plan + status, and expose one entitlement(org) check the whole app uses. Enforce limits on the server, where they can't be bypassed.

When to use

Different plans unlock different features or limits (seats, projects, API calls).
You need paywalls, usage caps, or "upgrade to continue" gates.
Handling trials, past-due, and cancelled states gracefully.

Model plans as data

// src/server/billing/plans.ts
export type PlanId = "free" | "pro" | "scale";

export const PLANS = {
  free:  { name: "Free",  priceId: null,            seats: 1,  projects: 3,   apiCallsPerMonth: 1_000 },
  pro:   { name: "Pro",   priceId: "price_pro",     seats: 10, projects: 50,  apiCallsPerMonth: 100_000 },
  scale: { name: "Scale", priceId: "price_scale",   seats: 50, projects: Infinity, apiCallsPerMonth: 1_000_000 },
} as const satisfies Record<PlanId, { name: string; priceId: string | null; seats: number; projects: number; apiCallsPerMonth: number }>;

Store on the org (synced from Stripe): planId, subscriptionStatus (active | trialing | past_due | canceled), currentPeriodEnd.

Enforce entitlements server-side

import { PLANS } from "@/server/billing/plans";

export function planFor(org: { planId: PlanId; subscriptionStatus: string }) {
  // lapsed subscriptions fall back to free limits
  const active = ["active", "trialing"].includes(org.subscriptionStatus);
  return active ? PLANS[org.planId] : PLANS.free;
}

export async function assertCanCreateProject(org) {
  const limit = planFor(org).projects;
  const count = await countProjects(org.id);
  if (count >= limit) {
    const e = new Error("Project limit reached for your plan");
    (e as any).status = 402; // Payment Required → show upgrade prompt
    throw e;
  }
}

Call assertCanCreateProject inside the create action — the UI may also read the limit to show a paywall (pairs with billing-and-pricing UI).

Pitfalls

Enforcing limits only in the UI — disable the button and check on the server; the endpoint is the real gate.
Ignoring past_due/canceled — decide the grace policy explicitly; default to downgrading to free limits.
Hard-coding plan rules across the app — centralize in PLANS; one edit changes every gate.
Counting usage without org_id scope — always count within the tenant.
No trial handling — treat trialing as active until currentPeriodEnd.

Hand-off

Typed entitlements enforced server-side. The pricing/paywall UI (billing-and-pricing in saas-ui-skills) reads the same PLANS; payments-stripe keeps the status fresh.