luanvdw-subscription

[warm galleon]

Hi! Do you have an existing subscription schedule that you want to update, or you only have a regular subscription?

[unkempt vortex]

Hi, thank you for the response.

Here is more context

We have a regular subscription that was created when a user creates a project (a project is an entity on our platform and the subscription is for this entity)

When they upgrade their project, my goal is to do this upgrade with a subscription scheduler so that the first invoice for this upgrade is in draft mode, as opposed to immediately finalised (which is what happens with a regular subscription)

So upon upgrading

I create a schedule with the existing subscription

*The existing subscription at this point has 4 subscription_items

const schedule = await stripe.subscriptionSchedules.create({
    from_subscription: subscription.id
})

Now in a subsequent call, I want to update the schedule to remove the old 4 subscription price items and add a different set of 4 price items.

As such I am looking to end the active phase with the original 4 sub_price_items and start a new phase with a new set of 4 price items

The reason for my original question in how to end this initial phase when creating a subscription schedule from an existing subscription is when I update the subscription schedule, with just the new phase under items, I am getting the following error;

You can not modify the start date of the current phase

So how would I go about ending the current phase and then starting a new one

and if I add a phase with the current price items, without a start date, then I get the following error

The subscription schedule update is missing at least one phase with a start_date

[warm galleon]

Can you share the request ID of the 2 errors your received?

Here's how you can find them: https://support.stripe.com/questions/finding-the-id-for-an-api-request

[unkempt vortex]

The subscription schedule update is missing at least one phase with a start_date to anchor end dates to.
req_i04J2exdQjKrAz

You can not modify the start date of the current phase.
req_9PL0LEYy85WuqG

[warm galleon]

Thanks! Give me a few minutes to look into this.

[sharp rune]

Hello. Taking over for soma here. Give me a few moments to catch up

[sharp rune]

Ok can you try to use the same update call but keep start date the same as its current value?

[unkempt vortex]

Hey! thank you for the response, just to make sure I understand

when updating the schedule, which phase should have the same start date as which current value?

Or can you perhaps provide a snipper so that I can see when updating the schedule how to update the current phase (with current subscription items) vs a new phase (with new price items)

Given the errors I previously shared, perhaps this would help guide the new conversation;

const updatedSchedule = await stripe.subscriptionSchedules.update(schedule.id, {
    phases: [
      // current phase inherited from_subscription when creating the schedule
      {
        items: [...currentItemsToRemove],
        // how would I end this phase?
      },
      // upgraded phase
      {
        items: [...newItemsToAdd],
        // how to start this phase?
      },
    ],
    end_behavior: 'release', // end the subscription schedule and keep the underlying subscription running
  })

[sharp rune]

You only have 1 phase though, correct?

[unkempt vortex]

I have the current active phase that is inherited from creating the schedule in the following manner

const schedule = await stripe.subscriptionSchedules.create({
    from_subscription: subscription.id,
  })

Then I want to update this schedule by ending the active phase and adding a new one starting now

[sharp rune]

Oh I see what you mean. You want to add a new one to transition to the new plans

[unkempt vortex]

Yes 100% 🙂

[arctic lotus]

You need to specify the start of the new phase or the end of the old one

You mentioned you wanted to use the end of the current billing period, so you can provide that timestamp from the subscription

So you could set the phase[0] end_date to be the subscription to be the subscription current_period_end eg.
https://stripe.com/docs/api/subscription_schedules/update#update_subscription_schedule-phases-end_date
https://stripe.com/docs/api/subscriptions/object#subscription_object-current_period_end

[unkempt vortex]

Ok thanks! So would this then represent a correct interpretation;

// Create schedule
const schedule = await stripe.subscriptionSchedules.create({
  from_subscription: subscription.id,
})

// Update schedule
const updatedSchedule = await stripe.subscriptionSchedules.update(schedule.id, {
  phases: [
    // current phase
    {
      items: [...currentItemsToRemove],
      start_date: schedule.current_phase?.start_date,
      end_date: 'now',
    },
    // initial transition phase
    {
      items: [...newItemsToAdd],
      end_date: phaseEndUnixTimestamp, // set to the 1st of the next month
    },
  ],
  end_behavior: 'release', // end the subscription schedule and keep the underlying subscription running
})

[arctic lotus]

I don't believe you can use now for the end date, you'd use it as the start date on the second phase, if that's what you wanted

[unkempt vortex]

I managed to get it working with the following,

const schedule = await stripe.subscriptionSchedules.create({
  from_subscription: subscription.id,
})

const updatedSchedule = await stripe.subscriptionSchedules.update(schedule.id, {
  phases: [
    // current phase
    {
      items: [...currentItemsToRemove],
      start_date: schedule.current_phase?.start_date,
      end_date: 'now',
    },
    // initial transition phase
    {
      items: [...newItemsToAdd],
      start_date: 'now',
      end_date: schedule.current_phase?.end_date, // the strategy here is to have this end on the end of the month
      // billing_cycle_anchor: ??
    },
  ],
  end_behavior: 'release', // end the subscription schedule and keep the underlying subscription running
})

[arctic lotus]

Ok great!

[unkempt vortex]

My final hurdle now is just to prevent the billing_cycle_anchor from being reset when doing the update

When the initial subscription is created the billing_cycle_anchor is set to be the 1st of every month

When creating the schedule with this subscription, the billing_cycle_anchor remains in tact

When updating the schedule however, the billing_cycle_anchor gets reset to "now" essentially when using;

billing_cycle_anchor: automatic or
billing_cycle_anchor: phase_start

when ideally what I need it to have

billing_cycle_anchor: phase_end to make sure that the anchor remains unchanged

Similar to when updating a subscription when you can stipulate:

billing_cycle_anchor: unchanged

[arctic lotus]

What are you changing in the items?

[unkempt vortex]

prices, I am essentially replacing 4 $0 price items with 4 billable price items

as the user is upgrading their project

[arctic lotus]

A free to non-free plan change will always invoice and cause the cycle to change:
https://stripe.com/docs/billing/subscriptions/upgrade-downgrade#immediate-payment

If you want to keep the cycle, don't use now -- use the current period end date as i noted earlier

[unkempt vortex]

So essentially only upgrade the user at the end of the month as opposed to now?

[arctic lotus]

correct

[unkempt vortex]

meh 🙈 that will be a bit of a blocker as this is a digital service, we cant have a user upgrade and then the upgrade only takes place at the end of the month 😂

Seems like our options are to not have a specific billing anchor... or forego the need to update invoices (i.e. find a way to keep them in draft mode)

[arctic lotus]

Do you want to charge the customer at the time of change or not?

That would necessarily change the billing dates if you wanted to charge them "now", right?