thomasst-Subscription Schedule | Stripe Developers | Page 1

limpid kernel Aug 31, 2022, 12:13 PM

#

👋 happy to help

#

When is a subscription schedule "not started"?
if the first phase is in the future

devout valley Aug 31, 2022, 12:14 PM

#

Doesn't the first phase represent the "current phase"?

limpid kernel Aug 31, 2022, 12:14 PM

#

the current phase changes with time

devout valley Aug 31, 2022, 12:14 PM

#

In what scenario would I have a subscription schedule (that's attached to a subscription) where the first phase is in the future?

limpid kernel Aug 31, 2022, 12:15 PM

#

when you want to schedule a subscription to start in the future

#

and not right away

devout valley Aug 31, 2022, 12:16 PM

#

Thanks. Can a subscription's schedule property ever refer to a schedule in a status that isn't in active status?

limpid kernel Aug 31, 2022, 12:18 PM

#

I'm not sure. What are you trying to achieve basically?

devout valley Aug 31, 2022, 12:18 PM

#

In general understand subscription schedule statuses and make sure my webhook handling code is doing the right thing.

limpid kernel Aug 31, 2022, 12:19 PM

#

just as a quick advice, you should probably avoid using schedules unless your use-case is really too complicated to be handled by subscriptions alone

#

make sure my webhook handling code is doing the right thing.
like what exactly?

devout valley Aug 31, 2022, 12:20 PM

#

When a subscription schedule goes past the last phase's end date, does it go to completed status and the subscription's schedule property goes to null?

limpid kernel Aug 31, 2022, 12:20 PM

#

if you can be precise I might be able to help

#

if the subscription schedule is not released than the subscription will be cancelled if that's what you're trying to figure out

devout valley Aug 31, 2022, 12:21 PM

#

In which case does a subscription schedule end up completed then?

#

You are implying it would either go released or canceled depending on the setting.

limpid kernel Aug 31, 2022, 12:23 PM

#

no what I'm saying that if the schedule is completed (not released or canceled) than the subscription would automatically be cancelled

devout valley Aug 31, 2022, 12:24 PM

#

Not if the schedule's end_behavior is set to release.

limpid kernel Aug 31, 2022, 12:24 PM

#

exactly

devout valley Aug 31, 2022, 12:24 PM

#

Or am I misunderstanding something?

limpid kernel Aug 31, 2022, 12:24 PM

#

no that's exactly it

#

https://stripe.com/docs/billing/subscriptions/subscription-schedules#completing-schedule

Subscription Schedules API

Learn about the Subscription Schedules object and how to use it.

#

sorry I may have been vague in my answer

devout valley Aug 31, 2022, 12:28 PM

#

If I have a subscription with end_behavior set to release, will both of the following happen after the last phase ends? 1) The subscription's schedule property is set to null, and 2) the subscription schedule's status is set to released?

limpid kernel Aug 31, 2022, 12:30 PM

#

The subscription's schedule property is set to null
I'm not sure about that

devout valley Aug 31, 2022, 12:30 PM

#

(and 3) the subscription schedule's subscription is set to null, and released_subscription is set to the previous subscription)

limpid kernel Aug 31, 2022, 12:30 PM

#

you can use test_clocks https://stripe.com/docs/billing/testing/test-clocks to try your different scenarios

Test your integration with test clocks

Learn how to move Billing objects through time in test mode.

#

I don't have the answer to these questions off the top of my head, I also need to test them out

devout valley Aug 31, 2022, 12:31 PM

#

I was able to test a few scenarios with releasing a subscription. However, I still don't understand when a subscription schedule would move to completed status.

#

you should probably avoid using schedules unless your use-case is really too complicated to be handled by subscriptions alone

The use cases are:

Change subscription billing interval (price ID) at the end of the billing period.
When a customer signs a contract, schedule a contracted price on the subscription, and after the contract is ended, revert back to the another price.

I'm not sure how I would do those things without schedules.

limpid kernel Aug 31, 2022, 12:40 PM

#

just fyi these are the common use-cases for schedules https://stripe.com/docs/billing/subscriptions/subscription-schedules/use-cases

Subscription schedules use cases

Learn how to use subscription schedules.

#

Change subscription billing interval (price ID) at the end of the billing period.
yes this sounds like a good use-case

#

but can also be done with subscriptions

devout valley Aug 31, 2022, 12:42 PM

#

can be done how with subscriptions?

limpid kernel Aug 31, 2022, 12:44 PM

#

you can change the price, set billing_cycle_anchor: "unchanged" and proration_behavior: "none"

devout valley Aug 31, 2022, 12:52 PM

#

Thanks.

#

I've been playing around with test clocks but I am not able to create a subscription schedule in completed status. If the end_behavior is set to release, and I advance to the phase's end date, the schedule moves to released status and not completed. So, what is the completed status?

limpid kernel Aug 31, 2022, 12:56 PM

#

when it is completed without a release

devout valley Aug 31, 2022, 12:57 PM

#

When would that happen? The only values for end_behavior are cancel and release, and there are already statuses for canceled and released.

limpid kernel Aug 31, 2022, 1:01 PM

#

end_behavior is optional

#

you can just not pass it

devout valley Aug 31, 2022, 1:02 PM

#

It defaults to release:

In [38]: ss=stripe.SubscriptionSchedule.create(from_subscription=s.id)

In [39]: ss.end_behavior
Out[39]: 'release'

#

And the docs say "Possible values are release or cancel with the default being release."

limpid kernel Aug 31, 2022, 1:04 PM

#

I guess this is in the case of creating it from a previously created subscription

#

let me try to test a couple of things out

devout valley Aug 31, 2022, 1:04 PM

#

Thanks

limpid kernel Aug 31, 2022, 1:05 PM

#

again, this is really intricate and without testing I wouldn't be able to give you answer off the top of my head

devout valley Aug 31, 2022, 1:05 PM

#

It would just be nice if those statuses were better documented, so we wouldn't have to test it all out.

#

Especially with an advanced API like schedules.

pure knoll Aug 31, 2022, 1:21 PM

#

Hello 👋 I'm taking over as tarzan had to step away

#

This is a long thread 🙂 can you give me a quick summary of what you're blocked on currently?

devout valley Aug 31, 2022, 1:25 PM

#

Thanks @pure knoll , I am trying to understand subscription schedule statuses. What I am not sure is how a schedule can end up in completed status. For example, if the end_behavior is set to release, and I advance to the phase's end date, the schedule moves to released status and not completed. So how can a schedule end up in completed status?

pure knoll Aug 31, 2022, 1:27 PM

#

Gotcha, I don't know much about this myself but let me look into it 🙂

devout valley Aug 31, 2022, 1:39 PM

#

Thanks, please keep me posted!

pure knoll Aug 31, 2022, 1:49 PM

#

quick question, have you tried not setting an end_behavior?

devout valley Aug 31, 2022, 1:54 PM

#

Yeah, and it defaults to release. Also the docs say that it's either release or cancel.

pure knoll Aug 31, 2022, 2:05 PM

#

Okay so end_behavior determines what happens to the subscription after the last iteration is complete.
So before the end behavior kicks in and either releases or cancels the schedule, the subscription schedule should be in completed status

devout valley Aug 31, 2022, 2:06 PM

#

Can you define "before the end behavior kicks in"?

pure knoll Aug 31, 2022, 2:06 PM

#

You can listen to subscription_schedule.completed webhook event in order to test this
https://stripe.com/docs/api/events/types#event_types-subscription_schedule.completed

#

as soon as the last phase of the subscription schedule is complete, the schedule looks at the end_behavior to figure out what to do with the sub.

devout valley Aug 31, 2022, 2:25 PM

#

@pure knoll but that's not what I'm getting, I get expiring and released, e.g. sub_sched_1Lad7FBSqAkKUXpQ4k6MbvoX

#

How would I set up a subscription schedule in a way where it triggers subscription_schedule.completed?

#

evt_1LcrmuBSqAkKUXpQTgYd1mCP is the released event.

pure knoll Aug 31, 2022, 2:35 PM

#

@devout valley can you try something for me? Instead of setting end_behavior to release , can you try cancel and see if that changes the events you're seeing?

devout valley Aug 31, 2022, 2:37 PM

#

It doesn't let me do that for existing subscriptions, but in this case it would just do a subscription_schedule.canceled event.

pure knoll Aug 31, 2022, 2:40 PM

#

With the end_beahvior set to cancel, I'm actually getting subscription_schedule.expiring , subscription_schedule.updated , subscription_schedule.completed and then subscription_schedule.canceled & subscription_schedule.deleted in that order

devout valley Aug 31, 2022, 2:41 PM

#

Does the resulting schedule have both completed_at and canceled_at set, and what's the final status?

#

And how did you set it up?

pure knoll Aug 31, 2022, 2:42 PM

#

Setting a fixed cycle on the schedule basically sets the end_behavior to cancel

Screen_Shot_2022-08-31_at_9.41.58_AM.png

devout valley Aug 31, 2022, 2:44 PM

#

What would the difference between the canceled and completed statuses be then?

pure knoll Aug 31, 2022, 2:45 PM

#

Does the resulting schedule have both completed_at and canceled_at set, and what's the final status?
yup that's correct.
Final state is completed

#

so I guess that'd be the difference

devout valley Aug 31, 2022, 2:46 PM

#

It's interesting because this doesn't happen when a schedule is automatically released. Is that on purpose or a bug?

pure knoll Aug 31, 2022, 2:46 PM

#

if you cancel the schedule before its completed then it'd be in canceled status
if the end_behavior with cancel is cancelling the schedule after completion then it'd be in completed status

#

It's interesting because this doesn't happen when a schedule is automatically released. Is that on purpose or a bug?
I'm thinking that's on purpose as the subscription is still going and is only released from the schedule

devout valley Aug 31, 2022, 2:48 PM

#

Hmm. It would be good to have those things documented.

#

Are you able to put in a request to improve the documentation? Since even Stripe devs seem to be having trouble explaining those.

pure knoll Aug 31, 2022, 2:48 PM

#

For sure, I can flag this internally and see if we can make it more explicit on the docs

devout valley Aug 31, 2022, 2:48 PM

#

Thanks

pure knoll Aug 31, 2022, 2:49 PM

#

NP! 🙂 Sorry it took a while

devout valley Aug 31, 2022, 2:54 PM

#

Also, in that scenario, do you still have the cancelled subscription ID on the schedule?

pure knoll Aug 31, 2022, 2:59 PM

#

do you mean on the subscription_schedule.canceled event?

#

or if you retrieve the schedule?

#

devout valley Aug 31, 2022, 3:00 PM

#

If you retrieve the schedule after it was cancelled.

#

I'd imagine the event would have it in its previous data then

pure knoll Aug 31, 2022, 3:00 PM

#

If you retrieve the schedule after it was cancelled.
yup it should still have it.

#thomasst-Subscription Schedule