#clayton_api
brazen prismBOT
👋 Welcome to your new thread!
⏲️ We'll be here soon! Typically we respond in a few minutes, but sometimes we might take a bit longer if the server is busy or if you have a particularly tricky question.
⏱️ We close idle threads, which makes them read-only. Once a thread is closed it won't be reopened, but you can always start a new thread if you have another question.
🔗 This thread will always be available, even after it's closed. You can find it again using Discord's search, or you can save this link: https://discord.com/channels/841573134531821608/1318945388249481256
📝 Have more to share? Add more details, code, screenshots, videos, etc. below.
Below are links to other discussions we've had with you in the past week in case you want to review that information. If your question is related to one of these previous discussions, please provide a comprehensive summary of the current state and what you need help with now. We help many users simultaneously, so a summary allows us to resolve your issue as soon as possible.
- clayton_api, 22 hours ago, 22 messages
- clayton_api, 6 days ago, 3 messages
sweet mauve
We were chatting about this yesterday morning. I'm trying to create a subscription in the future with a billing cycle anchor of the 1st of every month. After that I would like to be able to update the start date and have the anchor still remain at the 1st.
I had tried with Subscription Schedules but we went over that last time that it would not be possible. Your suggestion was using trial_end to set a "temporary" start date, for when a user does not know the exact time we want to start charging. Then when we know, we change the trial_end, essentially updating the start date of the subscription.
However whenever I do this update the initial billing_cycle_anchor_config is updated to be null, and the billing_cycle_anchor is changed to the trial end.
stone flax
Right, I remember. I still don't quite understand in what case you would want to update the start date?
In any case, if the subscription haven't started yet, I would suggest you to delete it and create a new one with the new start date.
brazen prismBOT
sweet mauve
If for whatever reason the checklist to complete a clients onboarding is finished quicker than expected, we need to be able to move up the date to start charging.
Regarding your suggestion, since the Subscription Schedules flow didn't work for this use case, we are creating an 'active' subscription with trial days. When we go to delete it, since it was 'active' it is only cancelling it and the instance is still viewable in the UI. If we allow unlimited changes to a subscription's date, this would clutter up a customer's account quickly with useless info.
My question still remains though, why would trial_end update nullify my current billing_cycle_anchor_config? Is this expected and is left out of the docs, or is it unexpected?
sweet mauve
Sounds good
sturdy phoenix
I suspect the billing anchor is changing because you're triggering proration
Can you try making the request while setting proration_behavior to none
sweet mauve
I will try. But I do need prorations to occur for the first month
If its a partial month
sturdy phoenix
Gotcha. Just give it a try as I'm not 100% sure what the expected behavior is supposed to be here.
Circling back to your original question though, theoretically any changes to the trial period might affect the billing cycle anchor because Stripe APIs automatically set the anchor to trial end date.
sweet mauve
Still has the same behaviour. It changes the billing_cycle_anchor_config to null, and sets billing_cycle_anchor to the trial_end
On creation, I can set trial end and billing_cycle_anchor_config, and everything is as expected. Its the update call that causes the issue.
sturdy phoenix
For example,
I subscribe to a product on April 1st with 30 day trial. So my billing anchor would be set to May 1st because there's when the trial ends.
Now if the trial is shortened to 20 days - my trial ends on April 20th and that's when Stripe needs to generate an invoice. Stripe won't automatically know what to do about the period between April 20th and May 1st in this case.
Ah wait
I think you need to combine billing_cycle_anchor with trial_end for your usecase
sweet mauve
If I subscribe to a product on April 15th with a 30 day trial, and set billing_anchor_config to { day_of_month: 1 }, proration_behavior to 'create_prorations', it looks exactly as I expect. First invoice on May 15th for a prorated amount until Jun 1st, and full month invoices after that.
If I update and say change trial to 20 days, and billing_cycle_anchor to 'unchanged' it still changes the subscriptions billing_cycle_anchor_config from { day_of_month: 1 } to null and it's billing_cycle_anchor to the trial end, making it charge a full month from May 5th to June 5th.
(I am using both those parameters in my update call. trial_end set to my new trial end, and billing_cycle_anchor set to 'unchanged')
sturdy phoenix
try setting an exact timestamp in the billing_cycle_anchor
sweet mauve
I can't. Docs say it can be set to either 'now' | 'unchanged'
sturdy phoenix
Oh wow, I definitely mixed up some docs. Sorry about that.. A bunch of ongoing threads atm..
sweet mauve
No problem. In the Create API it can be set to the exact timestamp.
sturdy phoenix
Can you share the request ID of the request you made while omitting proration_behavior ?
Ah I asked you to set it to none.
What happens if you just ommit the param from the request?
sturdy phoenix
Can you share both the requests?
sturdy phoenix
thanks
Give me a few to reproduce the issue as this seems to go against what the docs are suggesting.
sturdy phoenix
Hmm I'm seeing the same behavior. Let me reach out to my team and see if anyone knows what's going on here.
I have a feeling that this is expected with existing subscriptions versus doable on a new subscription.
Let me reconfirm though.
sweet mauve
In general there is a lot less customizability in the billing cycle anchor via update APIs (Subscriptions and Subscription Schedules). The create APIs you have full control. And updating via the UI, you have also full control. It would be helpful to have that same behaviour exposed in the API.
Regarding this current behaviour, it seems very counterintuitive to have billing_cycle_anchor set to 'unchanged', and the result having a changed billing_cycle_anchor.
signal rock
Howdy, just working with @sturdy phoenix on this internally
That parameter is ignored/superceded by the trial period which necessarily resets the BCA (billing cycle anchor)
Yes, the restriction on setting arbitrary future BCA changes in updates is somewhat limiting for some kinds of changes, but subscription schedules enabled those patterns
Since you can set up a future phase to reset the BCA
sweet mauve
Yes I've already tried my use case with Subscription schedules, but th invoicing generated is not as expected and it was deemed not possible to achieve with the Sub Sched API and that I should use Subscription and trial periods to achieve
signal rock
What was not as expected, specifically?
If, for example, you could set an arbitrary BCA in an update and do what you're trying directly, what invoice pattern would you expect?
sweet mauve
This is quoted from my conversation yesterday with vanya.
"The issue is when we create a subscription that is meant to start at a future date, the first two invoices are weird.
Lets say we want them to start being charged on Dec 20 with a billing cycle start on the 1st. I would expect invoice 1 to be a prorated Dec 20-Jan 1, and invoice 2 to be Jan 1-Feb 1. Instead Invoice 1 is Dec 20-Jan 20, Invoice 2 is Jan1-Feb 1 with a credit of unused portion from Jan 1-Jan 20 of the first invoice. I need to know how to set the equivalent of the "Billing Starting" field via the API, because when I set it to the 1st on the first phase the invoices are perfect"
signal rock
Hmm, do you have an example of a sub/schedule for that structure?
sweet mauve
Let me see. I may have deleted them
signal rock
See: https://docs.stripe.com/billing/subscriptions/billing-cycle#changing:~:text...
And how does that apply to the question here of updating a sub? I would expect the behaviour described here to allow you to get that result when creating the subscription.
After creation, a single update for that configuration may not be possible
sweet mauve
Here is a sub schedule with the strange invoice pattern.
sub_sched_1QWmGpS3LSlk1l2C92egN532
Let me describe our exact flow we are trying to create. Maybe that will let you understand better or recommend an alternative. At this point I'd rather be told 'we don't support this'. If that's the case I change our design save subscription info in our DB, create a daily cron to check if any subscriptions need to be started and just create a new subscription with billing_cycle_anchor_config to the first of the month.
A salesman signs a client, he know what products and coupons he promised them but not the exact date they will go live (because we have other systems to coordinate and the client needs to onboard in several steps), so he creates the subscription (in our UI) without a set date. Then when the client is done onboarding and we know the product will go live in a week (ingesting marketing relevant data takes about a week after onboarding) the salesman goes into our manage subscription UI and changes the date to be a week from now.
We want the subscription to start charging in a week, and the first invoice to be the prorated amount from that date until the 1st of the month, and subsequent invoice to be 1st-1st full month invoices.
There is also the possibility before the subscription has started charging, that a delay has happened and the salesman needs to change it to only start in 2 weeks. We need to update the subscription, while still respecting the same prorated and then 1st-1st invoicing pattern described above.
signal rock
Got it. Thanks for explaining.
signal rock
Here is a sub schedule with the strange invoice pattern.
sub_sched_1QWmGpS3LSlk1...
FOr this example, it does not appear there are any actual invoices generated since it is set to start a year from now and no test clock was used, so I can't review the invoice pattern (unless I've missed something, its possible).
signal rock
A salesman signs a client, he know what products and coupons he promised them bu...
With update contingency you describe, I expect this is strictly not possible with subscriptions alone, and would need to happen via a schedule.
I would like to understand the invoicing pattern here with a schedule and how its not what you need/expect, because I agree that I think this should be possible, but it might be the case that the invoices make different assumptions
Leaving aside the update flow, can you confirm you get the expected behaviour for new subscription creation?
sweet mauve
Yes create always looks good
signal rock
Because if so, an alternative you can consider is that if an update to delay the paid start date is needed before it occurs (ie, during the trial period), you could cancel that subscription and re-create a new one with the revised start date (trial_end).
sweet mauve
Right, but since subscription is considered active, cancelling it does not remove it from the UI in Stripe and clutters up the customer with useless canceled subscriptions. There is no limit to how many times someone may want to delay the subscription start, so I can't have that.
The previous technique I used (before create subscription with trial end and updating trial end) was Sub schedules. 1st phase starting now plus a year until next first of the month after that start date the with 'create_prorations'. Second phase was that first of the month until forever, with billing_cycle_anchor as 'phase_start'. This looked good. Didn't charge the client, and if they had waiting until the year passed the invoices looked good. A partial month followed by a full month charged on the first.
When a user set the date (ex: April 15), I would update the sub schedule to be 1st phase from user's desired date(April 15) until the next first of the month(May 1st) and 'create_prorations', and then 2nd phase the next 1st(May 1st) until forever and billing_cycle_anchor as 'phase_start'. This would not behave as expected and charge a full month on the first invoice from the user's desired start date until user's desired start date plus a month (April 15-May 15) . Then second invoice would start on the first for a full month(May 1-June 1) and credit the 'unused portion' from the previous invoice. (the overlap between the two invoice of May 1-May15).
signal rock
The first paragraph sounds like the case we were discussing and doing what you want to defer the start of the subscription. Is that right?
The second paragraph sounds like a later update to an existing subscription, which is a different scenario.
Or, can you clarify how the two pieces relate to one another and the future start sub scenario we were discussing?
sweet mauve
Lets say paragraph 1 is taking place on March 15. Paragraph 2 is taking place on April 1st.
paragraph 1 creates a sub sched, paragraph 2 updates that sub sched
brazen prismBOT
sweet mauve
Give me a few, I will revert my code to what it was before the suggested trial end workaround, when I was using subschedules to give you a clearer picture.
created sub schedule: sub_sched_1QXQVgS3LSlk1l2CZKy7KBt6
request_id: req_cTJhQ5zgHIs3eH
let me recreate, I made it more confusing by updating date and product list at the same time
sweet mauve
created sub schedule: sub_sched_1QXQcwS3LSlk1l2CsDBKigyJ
request_id: req_ZmvNzQlyoGH23q
Now I will update the date to today (so it actually generates the first two invoices)
update request ID: req_f5VACfBhRAXBCV
Unwanted/unexpected behaviour: The first invoice is for a full month even though the duration was set to a partial month, and create_proration was set as the proration_behaviour. The second invoice resets the anchor to the start correctly (the 1st of the month) but it now includes this 'unused portion' line item that seems to correct the mistake of the first invoice for overcharging.
Epexted behaviour would be invoice 1 is partial month prorated (1st phase start until 2nd phase start), second (and all subsequent months') invoice is full month.
potent hill
Looking...
Ah, I see the issue. You're setting the phase to end on the 1st, but that only applies to the phase, not the underlying Subscription. The Subscription itself, after that update, has a period that starts on Dec 18 and ends on Jan 18. That's why it's billing for that whole month.
The phase will end on the 1st, though, and then the second phase will take over and apply at that point.
Let me think about this for a bit...
sweet mauve
Oh I have an idea. What if I say the start of the first phase is also the first of the month, and set trial end as the real start.
That way the anchor of first phase will be the 1st, the trial will stop it from creating any invoice until trial_end. And then it should prorate that month invoice to be from trial_end to end of phase.
potent hill
Give it a try, but I don't think that will change the actual Subscription's period.
sweet mauve
I'm actually going to try something first. Sending the top level start_date as the first of the month, but the first phase start as when I actaully want it to start.
potent hill
The issue is that your update to the Subscription Schedule to change the start date is what's triggering creation of the Subscription itself. When the Subscription is first created it's going to default to a period length that matches the Price, which is one month in this case. The key thing to understand is that the Subscription Schedule phases do not equate to the Subscription's periods. They're separate things, and they have independent start and end dates.
sweet mauve
Ok. The real issue is that we can't set the billing_cycle_anchor with much customization. Its either 'automatic' or 'phase_start' which both seem to do the same thing, set it to the start of the phase.
potent hill
Yeah. Subscription Schedules don't support billing_cycle_anchor_config, which is really what we need. I'm trying to think of a workaround, but I haven't come up with anything yet...
sweet mauve
Yes exactly my thoughts
When the use case is updating a future subscription to start now, the work around I've done is query the sub sched, get all the info out of it like prices and coupons and create new Subscription from that, then cancel the Sub Sched (which since it was never active, removes it from the UI on stripe).
When the use case is updating a future subscription to start in the future, that work around does not work.
potent hill
Wait... why doesn't that work exactly? In that second case the Subscription doesn't exist yet, correct?
sweet mauve
Because the future subscription doesn't invoice as expected. You can't set the anchor properly with phases.
potent hill
Ah, I see.
The only approach I can think of is to schedule creation of the Subscriptions on your end so you can make use of billing_cycle_anchor_config.
Which, yeah, that's not great... but I don't think we support what you need on Subscription Schedules. I just can't think of a way to shorten the period of the first Subscription's Invoice the way you need.
sweet mauve
So I've created a sub sched with start date on the first of the month trial_end and on the dseired start date.
sub_sched_1QXRCJS3LSlk1l2CtvZf0bWi
sweet mauve
The only approach I can think of is to schedule creation of the Subscriptions on...
Yeah if I can't get this final idea to work, that was my back up. Save the info on our side and run a cron to check when active subscriptions can be created. But I needed to hear it conclusively from Stripe staff that the update API doesn't support our use case, to justify the added work.
potent hill
Wait, I think you're on to something there...
Curious to see how that attempt turns out. One variant if that doesn't work as expected is to try the exact same thing, but with billing_cycle_anchor set to phase_start instead of automatic.
sweet mauve
I think the update will cause limitation. I don't think I can set the start date in the past. (To set is as the first of the month if they choose a date in the currnt month)
potent hill
Yes, that's true.
sweet mauve
I would only need one phase in this case too, since the first phase will set the anchor to the 1st of the month.
potent hill
I just noticed you don't seem to be using a test clock for this. Do you know about test clocks?
sweet mauve
I do, but didn't know how to "undo" them or get out of test clock mode
potent hill
You can't, really. Test Clocks create little pockets of special time, and everything inside a Test Clock is designed to be ephemeral and will be deleted after a little while. They're great for testing a proof-of-concept like this, though, so you don't have to wait for things to happen in realtime.
More info about that here: https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage#delete-clock
sweet mauve
Thank you
I just tried with the trial end and while it looks good for the initial creation, the update case indeed doesn't work. The API response is not an error when I set the phase start to a past date, but it seems to just ignore it set the start date (and billing anchor) to today's date (or trial end, not sure where since they are both the same in my case)
sweet mauve
Curious to see how that attempt turns out. One variant if that doesn't work as ...
I tried and it responded, you cannot set it to phase_start when there is a trial.
sweet mauve
I just tried with the trial end and while it looks good for the initial creation...
This was the attempted schedule: sub_sched_1QXRS1S3LSlk1l2CCaAOFRP1
potent hill
Welp.
sweet mauve
Yep lol
potent hill
So, yeah, I think the next step for you is to set up the scheduling on your end, and the next step for me is to flag a feature request internally to support billing_cycle_anchor_config on Subscription Schedules.
sweet mauve
Two takeaways for me:
-Please add billing_cycle_anchor_config to update Subscription and Sub Schedules APIs. Its available through the stripe UI as Billing Starting and when I set that to the first it invoices properly.
-Add the fact that "That parameter [billing_cycle_anchor] is ignored/superceded by the trial period which necessarily resets the BCA (billing cycle anchor) " to the documentation somewhere (unless I just missed it). It was causing a lot of confusion to set billing_cycle_anchor to 'unchanged' and have it change. (Explained here #1318945388249481256 messageby synthrider)
potent hill
Flagged internally.
sweet mauve
Ok great. Thank you for that.
potent hill
For that second thing, you're talking about setting that on Subscription Schedules specifically, right?
sweet mauve
No that was for the initial issue of this thread. Subscription update was nullifying my billing_cycle_anchor_config and resetting my billing_cycle_anchor if I passed a trial_end. Even while specifying billing_cycle_anchor as 'unchanged'.
potent hill
Oh. Maybe I'm misunderstanding, but you should be able to do that, albeit not with unchanged, but by setting both the trial and the anchor to specific timestamps. See here: https://docs.stripe.com/billing/subscriptions/trials#combine-trial-anchor
potent hill
Oh, on update! That's what I was missing. Gotcha!
I will flag that documentation update.
sweet mauve
Its the theme with Subs/Subscheds. Update is missing some potentially really useful features
Thank you for your help. Happy holidays Rubeus.
potent hill
Happy to help! Sorry we didn't have better news. 😅