Migrating à-la-carte billing to plans-only in four safe phases

A SaaS product moved away from à-la-carte billing—where organizations paid per individual feature—toward a single plans-only model, because the old approach had become both operationally messy and error-prone. The core issue was structural: entitlement checks had to consult two sources of truth, per-feature subscriptions and an implicit plan, making every access gate fragile. Instead of ripping out the old columns in one shot, the team executed the change across four independently deployable phases: first plans were seeded, then feature gates switched to reading from the plan while writes still dual-ran, then existing organizations were backfilled onto real plans, and finally the old à-la-carte machinery was deleted.

This mirrors the classic expand-migrate-contract pattern from database schema work, applied instead to a domain/business-logic model: add the new structure alongside the old, migrate reads and then data, and only remove the old structure once nothing depends on it anymore. The feature gate collapses into one question—does this org's plan grant the feature—with edge cases handled separately, such as metered features needing quota checks rather than simple on/off entitlement, and internal admin orgs being granted the top tier permanently.

The billing migration also surfaced typical payment-gateway papercuts: an order reference exceeding a length limit, checkout failures from a null phone field, and validation errors that were silently swallowed—issues that tend to surface exactly when every org re-subscribes at once during a migration.

The broader takeaway is that changing entitlement logic deserves the same discipline as a schema migration: expand, migrate reads, migrate data, then contract, one deployable phase at a time. The overhead of four separate migrations is a small price compared to a billing outage that locks paying customers out of what they bought.