Stripe Subscription Schedule

Phases are the whole object

Everything a schedule does, it does through phases. Stripe: "use the phases attribute to define when changes occur and what properties of the subscription to change."

Two rules constrain the shape. "Phases must be sequential, meaning only one phase can be active at a given time," and "You can have up to 10 phases." That second limit is on current and future phases only: "Past phases don't count against this limit," so a long-running schedule does not run out of room as it ages.

Length is set either by a duration or by explicit dates, and Stripe has a clear preference. The `duration` parameter accepts `week`, `month` or `year`, and Stripe notes that "Using duration automatically sets the start_date and end_date properly." You can set the dates yourself, but the constraint is unforgiving: "The end_date of one phase has to be the start_date for the next phase." Stripe recommends duration instead, "Because manually setting the start and end dates is prone to errors."

Transitions need no intervention. "Phase transitions happen automatically after the end_date on a phase is reached. When a phase starts, Stripe updates the subscription based on the attributes of the next phase."

What a phase does to the subscription underneath it

This is the mechanism worth internalising, because it explains why a subscription can change without anybody touching it.

Stripe: "When a phase becomes active, all attributes set on the phase are also set on the subscription. After the phase ends, attributes remain the same unless the next phase modifies them, or if the schedule has no default setting."

So a phase is not a description of the subscription. It is a set of instructions written onto it. Attributes are sticky: a coupon applied in phase one persists into phase two unless phase two explicitly removes it, which is why Stripe's own promotional example includes a second phase whose job is to take the discount away.

Some attributes can be set in two places, on the schedule's `default_settings` and on individual phases, including collection method, invoice settings, default payment method and billing thresholds. The precedence is simple: a schedule attribute becomes the default for all phases, and where both are set, the phase wins.

One consequence catches integrations. If a subscription has a schedule attached, Stripe advises using the Subscription Schedule API to modify it "instead of the Subscriptions API," because "any modifications you make directly to the subscription might be overwritten by the subscription schedule when the next phase is entered." A quantity you changed by hand in March can silently revert in April.

Editing a subscription can create a phase you did not ask for

A subtler version of the same problem, and one that produces schedules nobody deliberately built.

Stripe lists attributes that, when changed directly on a subscription with a schedule attached, "might automatically create a new subscription schedule phase." They include `discounts`, `tax_rates`, `items`, `trial_end`, `application_fee_percent`, `add_invoice_items` and `automatic_tax`.

The worked example is a subscription with two items and a single phase mirroring its current state. Delete one item through the API and the attached schedule splits into two phases: "The phase that just ended and had two subscription items" and "The new phase that has just one item on the subscription."

When that split happens, Stripe copies a specific set of properties from the current phase to the new one: `proration_behavior`, `billing_cycle_anchor`, `cancel_at_period_end`, `description`, `metadata` and `pause_collection`. That last one is the surprise. A pause set on the subscription travels into a phase that was created as a side effect of an unrelated edit.

Proration has two separate settings, and they are easy to confuse

Stripe is explicit that "There are two different proration behavior settings that control how Stripe handles billing adjustments during subscription schedule changes," and mixing them up produces the wrong invoice at the wrong moment.

The **schedule-level** `proration_behavior` "controls how to handle prorations when updating a subscription schedule in a way that affects the current phase's billing configuration (such as changing prices or quantities)." It fires when you edit the schedule.

The **phase-level** `proration_behavior` "controls how Stripe handles prorations when transitioning to that phase." It fires when time passes and the phase begins. Stripe: "This setting applies specifically to prorations generated during phase transitions and is saved as a field on the phase."

Both take the same three values, and the third one is the one with accounting consequences: `create_prorations` (the default) generates pending invoice items, `none` creates no prorations, and `always_invoice` will "Generate prorations and immediately create an invoice when entering this phase." An `always_invoice` phase transition is therefore a billing event on a date chosen months ago, not on a billing cycle boundary.

Stripe adds a practical note for anyone fixing this before it bites: "If you need to change how a future phase transition handles prorations, update the proration_behavior setting on the future phase before it becomes active." How prorations themselves are calculated and recorded is covered in the Stripe proration entry.

The five statuses, and the two ways a schedule ends

Stripe defines `status` as "The present status of the subscription schedule," with five values: `not_started`, `active`, `completed`, `released` and `canceled`.

The first two are self-explanatory. `completed` is the ordinary ending: "Subscription schedules end after the last phase is complete." The last two are things you do on purpose, and they are not interchangeable.

**Releasing** detaches the schedule and leaves the billing alone. Stripe: "Releasing a subscription leaves it in place but removes the schedule and any remaining phases." The schedule records what it used to manage in `released_subscription`, documented as the "ID of the subscription once managed by the subscription schedule (if it is released)."

**Canceling** takes the subscription with it. Stripe: "Canceling a subscription schedule cancels the subscription as well." Both operations have the same precondition, which is that the status is `not_started` or `active`.

The same fork exists as an automatic setting for the natural ending. `end_behavior` is documented as the "Behavior of the subscription schedule and underlying subscription when it ends," with `release` the default: "release will end the subscription schedule and keep the underlying subscription running. cancel will end the subscription schedule and cancel the underlying subscription."

Installment plans are the clearest case for `cancel`. Stripe's own example charges a fixed number of iterations and sets `end_behavior` to cancel because "In an installment plan, the subscription isn't needed anymore." One detail for anyone watching for the cancellation date: the subscription's `cancel_at` "isn't set until the subscription transitions into the final phase," so it will not appear on the subscription in advance.

The first invoice does not behave the way a new subscription does

This is a small difference with a real effect on when revenue appears, and it applies specifically to schedules.

Creating a subscription directly finalizes its first invoice immediately. Creating one through a schedule does not. Stripe: "Unlike when you create a subscription directly, the first invoice of a subscription schedule with collection_method set to charge_automatically behaves like a recurring invoice and isn't immediately finalized at the time the schedule's subscription is created. The invoice begins in a draft status and is finalized by Stripe approximately 1 hour after creation."

Stripe frames the hour as an editing window: "You have 1 hour to edit the invoice. Later, the invoice auto-advances to open or paid status, depending on the outcome of the asynchronous payment attempt at finalization time."

For bookkeeping, the practical reading is that a schedule started at 4:55pm produces its first finalized invoice at around 5:55pm, which can be the following day in your reporting timezone. It is a one hour gap, not a behaviour change, but it is enough to move an invoice across a period boundary at month end.

How to find a schedule you did not create

Schedules appear without being asked for, and knowing where they come from saves a lot of confusion.

Stripe creates them automatically in at least one common flow: a customer scheduling a downgrade through the Customer Portal produces a schedule, and Stripe recommends capturing the ID from the `subscription_schedule.created` webhook "when Stripe creates it automatically." The phase-splitting behaviour above is another source.

You can also attach one deliberately to an existing subscription by passing `from_subscription`. Stripe: "Passing the subscription IDs in this way creates a schedule with one phase that's based on the current billing period of the subscription."

Stripe's advice on the lifecycle is worth following if you store these IDs: keep the schedule ID alongside the subscription ID for future updates, and "Discard the subscription schedule IDs when a subscription schedule is released," which the `subscription_schedule.released` webhook tells you about.

One restriction is worth knowing in advance, because it turns a schedule into a blocker. A subscription with an attached schedule cannot be paused with Stripe's pause subscription feature. Stripe's own remedy in that case is to release the schedule first.