Stripe: downgrade a user at “period end”

Most of the solutions presented here look like hacks after stripe’s release of subscription schedules, which is probably the most elegant solution. In fact, stripe documentation has an example illustrating exactly the same scenario here.

Step 1: Get current_period_end value from the existing subscription that you wish to downgrade.

Step 2: Create a new subscription schedule from the existing subscription.

$subscriptionSchedule = $stripe->subscriptionSchedules->create([
  'from_subscription' => 'sub_G678SASEGF',
]);

Step 3: Update the newly created schedule with two phases. phase 0 is the current phase that ends at current_period_end and phase 1 is the next phase that start at current_period_end with the downgraded price plan.

$stripe->subscriptionSchedules->update(
  $subscriptionSchedule->id,
  [ 
    'end_behavior' => 'release',
    'phases' => [
      [
        'start_date' => $current_period_start,
        'end_date' => $current_period_end,
        'items' => [
          [
            'price' => $current_price_id
          ],
        ],
      ],
      [
        'start_date' => $current_period_end,
        'items' => [
          [
            'price' => $downgraded_price_id,
          ],
        ]
    ],
  ],
]

You can always check the subscription object to see if there is a schedule active, and then retrieve the schedule to tap into any future downgrades. The advantage of this approach is that it could be applied to any downgrade and/or billing cycle change. with a multi plan approach described earlier in the answers, one subscription can only have items with the same billing cycle.