Killing à-la-carte: migrating a feature-gating model to plans-only

TL;DR Moved a SaaS from à-la-carte feature subscriptions (pay per feature) to plans-only (pay for a tier, get its features). Did it in four phases so nothing broke mid-flight: seed plans → gate on plans → migrate orgs → delete the old machinery. Lesson: model migrations are safest as expand → migrate → contract , not a big-bang swap. The problem The old billing let an org subscribe to individual features à la carte. Flexible on paper, painful in practice: entitlement logic had two sources of truth (per-feature subscriptions and an implicit plan), and every gate had to check both. Time to collapse it into one model — you buy a plan , the plan carries the features. The trap with this kind of change is the temptation to rip out the old columns and ship. Do that and every in-flight subscription, every gate check, and every webhook that still speaks the old language breaks at once. The phased plan I ran it as four ordered migrations. Each phase is deployable on its own and leaves the app working. Phase What it does Why this order F1 Seed Plans into the prerequisite chain New model must exist before anything reads it F2 Gate features on the plan, not the feature-sub Reads switch over while writes still dual-run F3 Deploy op migrates existing orgs onto a plan Backfill — nobody left on the old model F4 Remove the à-la-carte machinery Contract — safe only after F3 This is the expand/contract pattern applied to a domain model, not just a schema. Expand (F1) adds the new thing alongside the old. Migrate (F2–F3) moves reads then data. Contract (F4) deletes the old thing once nothing points at it. F1 seed F2 gate on plan F3 backfill orgs F4 drop features ┌────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ plans │ --> │ reads: plan │ -> │ every org on │ -> │ delete a-la- │ │ exist │ │ writes: both │ │ a real plan │ │ carte code │ └────────┘ └──────────────┘ └──────────────┘ └──────────────┘ safe safe safe safe Gating on the plan The gate collapses to a single question