メニュー
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.
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
SOC 職業分類に基づく
| name | subscription-billing |
| description | 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. |
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.
// 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.
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).
past_due/canceled — decide the grace policy explicitly; default to downgrading to free limits.PLANS; one edit changes every gate.org_id scope — always count within the tenant.trialing as active until currentPeriodEnd.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.
Use when building API endpoints or server actions — validate every input with zod, return consistent typed JSON errors, set correct status codes, and authenticate/authorize before touching data.
Use when adding sign-in/sign-up or session handling to a SaaS app — set up Auth.js (NextAuth) or a hosted provider with secure sessions, OAuth + email, and server-side session checks that protect routes and actions.
Use when controlling what a user may do — implement role-based access control with a central permission map, server-side checks on every mutation, and a typed `can()` helper instead of scattered role string comparisons.
Use when work shouldn't run in the request path — offload emails, webhooks, exports, and scheduled tasks to a queue or job runner with retries, idempotency, and dead-letter handling instead of blocking the user.
Use when querying or mutating the database from the app — wrap Drizzle in server-only, tenant-scoped functions instead of calling the ORM from components, so every read/write is typed, testable, and isolation-safe.
Use when designing the Postgres schema or setting up Drizzle ORM — model users, organizations, memberships, and tenant-scoped tables with the right keys, indexes, timestamps, and migrations from day one.