(v48.0.0 breaking changes) - Help me understand the move from Subscription.CurrentPeriodEnd to SubscriptionItem.CurrentPeriodEnd

[sion-corn]

Describe the bug

According to the v48.0.0 release notes:

Remove support for CurrentPeriodEnd and CurrentPeriodStart on Subscription

Before the breaking changes introduced in v48.0.0, in my stripe repository, I have been extracting the subscription's CurrentPeriodEnd value like this (currentSubscription is a Subscription object):

user.StripeUtcSubscriptionPeriodEnd = currentSubscription.CurrentPeriodEnd;

should I be doing it like this instead (the Items property is a List<SubscriptionItem>):

user.StripeUtcSubscriptionPeriodEnd = currentSubscription.Items.Data.Max(x => x.CurrentPeriodEnd);

If this is not the correct approach, then please help me understand why CurrentPeriodEnd property was removed from the Subscription object, and how we should be thinking about the CurrentPeriodEnd property as it now relates to the SubscriptionItem object. I tried searching the Stripe docs but could not find anything related to this.

To Reproduce

N/A

Expected behavior

N/A

Code snippets

OS

win11

.NET version

.NET9

Library version

stripe-dotnet v48.0.0

API version

2025-03-31.basil

Additional context

No response

[xavdid-stripe]

There's additional information about the change in the API changelog, specifically this section: https://docs.stripe.com/changelog/basil/2025-03-31/deprecate-subscription-current-period-start-and-end, which includes information about the newer way to be thinking about subscription start and end dates.

[jar-stripe]

Hi @sion-corn , just wanted to check in. Did @xavdid-stripe 's answer solve your issue here?

[sion-corn]

@xavdid-stripe @jar-stripe the documentation provided by @xavdid-stripe just re-states the release notes - it does not explain why the changes went into effect. I am asking for an explanation of what motivated these changes, since it seems like we should no longer be thinking about the CurrentPeriodEnd as something that describes a Subscription, but rather a SubscriptionItem instead. Why, and what does this imply from the standpoint of how subscriptions should work?

[remi-stripe]

@sion-corn That's good feedback, we definitely should explain the why even though the real reason is not public yet!
We are planning to support having Prices with different billing cycles on the same Subscription. For example combining a $10/month Price with a $100/year Price and have the Subscription automatically Invoice for the right thing on the right schedule. This has been a top ask for as long as we've had support for multiple Prices on one Subscription (2017) and is really hard to do properly today.

When we ship support for this, it won't make much sense to have a top-level period anymore and we wanted new integrations (and developers upgrading) to plan for this future change in advance so that they can adopt it if they need it later. That's why each SubscriptionItem now has its own period represented.

[sion-corn]

@remi-stripe thanks for the explanation, that clears things up nicely. So if I don't plan on introducing Prices with different billing cycles on the same Subscription and don't want to change my schema, the following two lines are equivalent, right?

legacy (i.e. before stripe-dotnet v48.0.0)
user.StripeUtcSubscriptionPeriodEnd = currentSubscription.CurrentPeriodEnd;

new (i.e. after stripe-dotnet v48.0.0)
user.StripeUtcSubscriptionPeriodEnd = currentSubscription.Items.Data.Max(x => x.CurrentPeriodEnd);

[remi-stripe]

Yes that sounds reasonable as an approach.
But don't underestimate how easy it might be for one of your Subscriptions to get into a state where it has multiple billing cycles in the future. It's especially true as that feature will come to the Dashboard and might be easy to adopt without even realizing this or the impact to your code if someone on your team does a manual change.

Doing a parallel to what happened years ago: developers would swear they never planned to have more than one Price on a Subscription. And they were right in the sense that their code never did this. But support agents or people on a sales team ended up making changes in the Dashboard without ever realizing that could break something. And the code "just worked" (or appeared too) because it looked at just one Price in items and never expected more than once.

All this to say: if I were you I would at a minimum add a bit of code that checks the period of each SubscriptionItem and trigger some alert or email in case there's ever a mismatch so that you can react to it.

[sion-corn]

@remi-stripe Got it, thanks for the clarification! ✌