How do I map Stripe subscription schedules to deferred revenue?

What a phase actually changes

A subscription schedule's phases attribute defines when changes happen and what properties of the subscription change at each point — price, quantity, coupons, tax rates. Phases must be sequential (only one active at a time), and Stripe supports up to 10. When a phase becomes active, Stripe updates the underlying subscription to match it automatically; you don't have to separately call an update on the subscription itself once the schedule is in place.

How Stripe's own Revenue Recognition reads a schedule

Subscriptions create invoices on each cycle, with each subscription item corresponding to an invoice line item, and the period of that line item populated automatically from the subscription item's period. Stripe's Revenue Recognition product treats each invoice line item as its own performance obligation: when the invoice finalizes, it defers the total recognizable amount and amortizes it evenly across the line item's period. If a line item has no period set, Revenue Recognition recognizes the full amount immediately at finalization instead — which is the detail that matters most when mapping a schedule's phases to deferred revenue correctly.

Setting one up

The mechanics are the same whether the change is an upgrade or a downgrade — only the price and quantity in each phase differ. What matters for revenue recognition is that each phase's items carry a real price associated with a recurring interval, so the resulting invoice line items get a period Stripe can amortize over, rather than reading as one-off charges.