Stripe Subscription Schedules - final phase is scheduled twice

I’ve been struggling to correctly set up a subscription schedule in Stripe (so that the updated plan executes once, and after that execution, it reverts to the regular subscription with the new price without any further scheduling).

Here’s my situation:

• I currently have an active subscription (with its own plan and price) and I’ve scheduled that, starting from the next billing cycle, a new subscription (with a different plan/price) should take effect.

This part is working fine for me :)

How I’m handling the change and scheduling:

1. I create a subscription schedule from my current subscription:

    const scheduledSubscription = await this.stripe.subscriptionSchedules.create({
        from_subscription: stripeSubscriptionId,
    });

2. I retrieve the schedule and proceed to update it. In the first phase, I set the current subscription to end at the end of the period, and from the new period onwards, it should transition to a subscription with a different price (see price: newPriceId):

    // Update the schedule with the new phase
    const downgradedSubscription = await this.stripe.subscriptionSchedules.update(scheduledSubscription.id, {
        phases: [
            {
                items: [
                    {
                        price: scheduledSubscription.phases[0].items[0].price,
                        quantity: scheduledSubscription.phases[0].items[0].quantity,
                    },
                ],
                start_date: scheduledSubscription.phases[0].start_date,
                end_date: scheduledSubscription.phases[0].end_date,
            },
            {
                items: [
                    {
                        price: newPriceId,
                        quantity: 1,
                    },
                ],
            },
        ],
    });

The issue I'm facing during these steps is as follows:

1. This is the default state before running the code above:

2. This is the state after calling subscriptionSchedules.update with the two phases:

3. After advancing the clock by one month:

At this point, I expect the state to revert to what it was in step 1 (with no update scheduled and the new subscription active).

4. However, it’s only after another monthly cycle that I achieve the desired state (a normal subscription with no update scheduled):

This is actually the expected behavior; let me explain. When you create a SubscriptionSchedule, each phase has its own start_date[0] and end_date[1] or a number of iterations[2] that defines how much time that phase will be active. If neither [1] or [2] is mentioned by default, the phase would run only for 1 iteration. Once the last phase has ended, then the end_behavior[3] will kick in. You haven't specified any, so it defaults to release which means that the subscription won't have any schedule attached to it anymore.

In your case, this means that until the end of the second month the subscription is still managed by the schedule and only at the start of the third month will the schedule release the subscription.