AI Pricing Migration: Grandfathering, Dual-Track Quoting, and Reversible Rollout

When a team decides to raise the Pro price, the most dangerous implementation is to directly modify a single plan configuration, so that new signups, existing monthly payers, annual payers, trials, and enterprise contracts simultaneously see the new rules on the next request. Some users will immediately be over-charged Credits, some bills will produce unexpected proration, and long tasks will start at old quotes and end with new entitlements. Even if the business decision is correct, the lack of migration control can turn a price adjustment into a trust incident.

AI Product Pricing Models handles model selection; AI SaaS Entitlement Snapshots handles runtime enforcement after taking effect. This article only migrates contracts, prices, cohorts, and billing schedules, and designs compensation; it does not decide prices. Examples must go through compliance review.

Prices, entitlements, and migration rules are all versioned

After a price object is published, do not modify the amount or unit in place; create a new priceVersion, keeping the old version for existing subscriptions and historical reconstruction. The plan version simultaneously binds price, currency, billing cycle, included usage, overage meters, Credits rules, entitlement version, tax behavior, and effective interval. The payment platform's Price ID is just a mapping, not a complete commercial contract.

migrationId: pro-v3-to-v4
fromPlan: pro-2025-11
toPlan: pro-2026-09
cohorts:
  newSignup: {effectiveAt: 2026-08-01T00:00:00Z}
  existingMonthly: {effectiveAt: next_renewal, noticePolicy: notice-v2}
  existingAnnual: {mode: grandfather, until: current_term_end}
credits:
  conversionPolicy: credits-v3-to-v4
  preservePurchasedExpiry: true
rollbackDeadline: before_invoice_finalization

Grandfathering is an explicit eligibility, not a temporary judgment like created_at < some day. Cohort records include the customer, original plan, which prices/entitlements to retain, end conditions, notification version, and exception approvals. Permanent retention, retention until the end of the current contract term, and retention for several renewals have different legal and revenue implications, and cannot be reduced to a single legacy=true.

Quote on dual tracks first, don't deduct on dual tracks first

Generate old and new invoice previews for the same subscription, billing period, usage, tax, and discount, and compare recurring, usage, proration, Credits, tax, and due date. Report a fixed proration_date and subscription input revision/hash, and reuse them as-is during execution; shadow results only write reports and do not create payable invoices. Stripe Test Clock can cover supported objects' renewal, trial, and schedule boundaries.

The difference gate checks at least: no unknown meter/price, currency unchanged or explicitly converted, quantity not reset by default, the same usage counted only once, proration consistent with notification policy, Credits net amount conserved, and tax fields complete. Each account generates a readable diff and machine hash; the preview customer service sees must use the same input version as the migrator.

Each account/phase has only one migration record, saving the Stripe subscription_item.id, expected old price/quantity, schedule revision, and preview hash. The worker re-reads and performs CAS before execution, and stops and recomputes if it does not match; calls use stable idempotency keys, querying first on timeout before retrying. You must use the original item ID to swap the price in place, and cannot omit it and then add a second item; after completion, assert that the migrated component has exactly one active item, and that the price, quantity, and schedule equal the target version.

Credits cannot be temporarily converted based on model cost changes. The conversion policy fixes source/target units, precision, rounding, remainder, purchase and promotion batches, validity period, and refund rights; if fair conversion is not possible, let old Credits be consumed on old meters or explicitly compensate. Migration only appends ledger transactions and does not directly modify balances.

Phased rollout from new customers to renewal cohorts

First let new signups enter the new plan, observing payment success, entitlements, usage, refunds, and gross margin; then open voluntary migration, and finally handle renewal cohorts per notification and contract. Each stage sets a minimum billing sample and complete cycle, and does not migrate all annual customers at once just because short-term signup conversion looks normal.

Feature Flags can control the new quote UI and migration worker traffic, but cannot randomly decide already-signed contract prices. Disabling an AI Feature Flag only rolls back the code entry; durable cohort assignment, payment schedules, and entitlement snapshots are business facts. Traffic staging can draw on Model Serving Canary Rollout, with the stop gate changed to invoice diff, payment failures, support contacts, refunds, usage anomalies, and gross margin.

User notifications show old/new prices, included usage, overage rules, effective date, Credits handling, and cancellation or downgrade paths, not just "plan upgrade". High-risk changes retain confirmation evidence and send time. Early interviews can refer to AI Willingness-to-Pay Interviews, but research conclusions cannot replace explicit notifications to existing customers.

Use different rollback methods before and after taking effect

When issues are found in a future-effective stage, stop allocating new cohorts, cancel the erroneous subscription schedule phase, restore the old price/plan resolver, and invalidate entitlement snapshots that have not yet executed. Tasks already running under old terms continue to use bound versions, and prices cannot be mixed mid-stream. Regenerate previews to prove the old path is restored before reopening.

When the price has taken effect but the invoice is not yet finalized, first pause auto-advance, and re-verify the actual draft line items, net amount, and input hash against the approved preview; if inconsistent, fix and preview again. Changes that immediately invoice or charge must go through a pending update/payment gate, and cannot assume there is still a finalization window afterward. After the bill is finalized or payment is collected, history cannot be deleted or only the subscription pointer changed; instead, use credit notes, refunds, compensating Credits, or subsequent adjustments, and make rollback idempotent.

Acceptance migration with the full lifecycle

Test new signups, renewals, upgrades, downgrades, trials, different currencies, discounts, tax, overage, duplicate workers, omitted item IDs, concurrent plan changes by users, preview/draft drift, auto-finalize, and out-of-order Webhooks. Run fixed samples from quote through entitlement, usage, invoice, payment, and refund, and verify versions and net amounts for each stage.

The release dashboard shows allocation count, preview mismatch, migration success, billing failure, refund, support contacts, churn, and gross margin by migration/cohort; raw accounts remain in audit rather than metric labels. Only after completing at least one real renewal window with no reconciliation differences can the old path be closed; even if new subscriptions are stopped, old prices and rules are retained until the last grandfather contract ends. The core of reversible pricing rollout is not that you can always pretend no price change happened, but that every customer knows the applicable version, and every effective stage has a legal, reconcilable exit action.

Further Reading

• AI Product Pricing Models
• AI Feature Flag
• Model Serving Canary Rollout
• AI Willingness-to-Pay Interviews