#tayls-pdq_best-practices
edgy onyxBOT
đ 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/1224833081568133160
đ Have more to share? Add more details, code, screenshots, videos, etc. below.
woven wyvernBOT
vivid spade
Hi roadrunner
tired wharf
Can you share more details?
vivid spade
Sure.
tired wharf
I'm not sure what you mean exactly by "several methods"
vivid spade
Yea, absolutely. Let me copy em from the docs:
- Update the subscription, then update the current subscription item with a new price id
- Update the subscription, deleting the previous subscription item while adding a new subscription item
- Update the subscription item directly.
tired wharf
Ah, I think there's an action missing. You mean "several methods" of updating a subscription, right?
vivid spade
In this case it'd be several methods of changing the price of a subscription
The help doc is about upgrading or downgrading subscriptions. Which I take is Stripe lingo for changing prices.
Though, I don't think updating the subscription item directly would be of use to us here, because we also need to pass the proration_behavior=none flag, to prevent charging for the price increase for subscription items that customers have already bought. (I.e., we don't want to upcharge customers for their current term, just incase the price for the next term)
However, we're worried about:
- Prorations being incorrect, particularly when combined with schedules
- Pre-billed customers having a bad experience.
tired wharf
Gotcha!
There are ultimately several ways to do this due to the different ways a merchant may want to handle these kinds of changes (immediately vs. on a schedule, proration vs. no proration)
vivid spade
Okay, I think we're in the Immediately and no proration track.
That is, we want the change to take effect immediately, for all future charges. But we don't want to prorate changes / raise charges for the current term.
If we're on that track, which method is best?
tired wharf
If all you're doing is updating the price for a given Subscription Item (and not making other changes to the Subscription), you should update the item: https://docs.stripe.com/billing/subscriptions/upgrade-downgrade#update-the-subscription-item
This is also assuming you're not creating usage records/not working with usage-based billing
vivid spade
What are usage records?
Would updating the subscription item cause a proration to happen?
tired wharf
Would updating the subscription item cause a proration to happen?
when updating the item, you can pass proration_behavior: none to disable prorations: https://docs.stripe.com/api/subscription_items/update#update_subscription_item-proration_behavior
vivid spade
How would that work when updating a subscription schedule with multiple phases? I assume each phase has it's own subscription items with their own subscription_item id?
tired wharf
What are usage records?
Usage records are applicable only if you have usage-based prices, e.g., a customer pays $1/request for their first 1000 API calls, pays $0.75 for 1001-5000, etc., and you want Stripe to calculate the total price for their usage
vivid spade
Gotcha. Understood
tired wharf
As for schedules, you'll need to update the item for a specific phase, and pass proration_behavior for that phase: https://docs.stripe.com/api/subscription_schedules/update?lang=ruby#update_subscription_schedule-phases-items
I recommend playing around with these updates + Schedules using test clocks to see things in action: https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage?dashboard-or-api=api
vivid spade
Okay, what about pre-billed subscriptions?
tired wharf
By pre-billed, are you referring to this beta? https://docs.stripe.com/billing/subscriptions/sales-led-billing#prebill-customers-in-advance
vivid spade
Yes, we use it for many customers.
tired wharf
Gotcha
vivid spade
The issue we have there is that we don't want to "undue" the pre-bill by raising the price either in the current term or the subsequent term. Since that would mean that the custoer actually owes money for their next term, even though they already pre-billed
tired wharf
We're not experts on betas in this channel so I can't speak to the best way to handle pre-billed customers when changing prices. I recommend working with the contact who helped you get started with this beta
Based on those docs, it sounds like you probably want to use Amendments but your contact would know best
vivid spade
Amendments?
vivid spade
Can you show me the Amendment / Contract endpoints in the API? I'm not familiar with these features
tired wharf
I'm not sure if Amendments would solve your use case but it sounded promising based on the doc I linked above and what you've shared so far. I recommend continuing this discussion with the Stripe contact who enrolled you in the prebilling beta
vivid spade
Okay, our contact that enrolled us was our integration engineer that helped us on-board onto Stripe. Though we don't have them anymore, since we're no longer on the onbarding phase.
Do the Amendments have endpoints I could research myself?
tired wharf
Ah, I see. Your contact may have shared links to beta docs when they first enrolled your account in the beta. If they didn't, I recommend reaching out to our Support team about this: https://support.stripe.com/contact/
vivid spade
Understood.
In that case, could you help me understand why editing the subscription item is the preferred method? Over editing the subscription item through the subscription?
tired wharf
Sure! I recommended it in this case since you mentioned no other changes are being made to the Subscription at the same time
But you can really use either method: updating the Subscription or updating the SubscriptionItem
vivid spade
Gotcha. So there isn't a preferred method, just many options?
If so, is there any impact on prorations depending on which method we use?
tired wharf
Yep, exactly, as long as you pass your preferred value for proration_behavior
vivid spade
Sounds like the proration behavior would be the same in all cases then?
tired wharf
Right, since you don't want prorations, you would pass proration_behavior: none to disable prorations
vivid spade
Gotcha. Although I think our concern is mostly about proration events that happen after the subscription is updated. E.g.,
In July Subscription is made with price X
In December subscription is updated to price Y
In April (before the renewal period), subscription is prorated to increase quantity by 1, to 3.
We're concerned that Stripe won't calculate the proration correctly. Since we've already seen instances where the proration behavior incorrectly refunds the amount of unused time. For example, in this case, we're concerned about the proration logic using the updated Price Y to discount the remaining time, not the original Price X. (In our original case, importing subscriptions with discounts caused the proration to not consider the discount when refunding unused time, therefore undercharging customers)
tired wharf
Just to be clear, is the example above with prebilling?
vivid spade
No, just with a regular subscription
tired wharf
Have you tested this out? If so, could you provide the example Subscription ID?
I assume Price X and Price Y are annual prices?
vivid spade
I have not tested this, no.
I assume Price X and Price Y are annual prices?
Yes, all of our prices are annual recurring prices.
If you'll give me a few moments, I'll test this and post the results
tired wharf
For example, in this case, we're concerned about the proration logic using the updated Price Y to discount the remaining time, not the original Price X.
It sounds like you probably want to update the subscription to Price Y using a schedule so the update to Price Y doesn't take effect until July/the next billing cycle
vivid spade
No, we actually want to update the subscription today so that any prorations/pre-billings happen on the new price. The business requirement is that: "all future charges are at the new price" not "all future charges after the effective date are at the future price"
This is the result that I got- the original price was 1500, and the new price was 1575
Looking at the proration, the item did use the updated 1575 price.
tired wharf
Can you share the Subscription ID?
vivid spade
sub_1P1G2XKVm4WHjNVwELgytGXt
tired wharf
Hm, something seems to be happening with Schedules here. Are you familiar with some backend process that uses Node and creates subscription schedules from existing subscriptions?
vivid spade
Yea, we do have a service that writes back a schedule. Though I don't think that's pertinent in this example. Sorry for not spelling that out first
Though, we will have to solve the problem when it's related to schedules as well
tired wharf
I think the schedule is throwing me off here. So just to recap, you've created a subscription with a $1500 annual price. You then update a subscription item to a $1575 annual price with proration_behavior: none. then I see an update to the schedule: the quantity of the item in the current phase is updated to 2, with proration_behavior: always_invoice: https://dashboard.stripe.com/test/logs/req_oGnh2jb2cpbV41
So the question is why are we using the $1575 price to calculate the proration?
vivid spade
So the question is why are we using the $1575 price to calculate the proration?
Yea
You then update a subscription item to a $1575 annual price with proration_behavior: none. then I see an update to the schedule: the quantity of the item in the current phase is updated to 2, whith proration_behavior: always_invoice: https://dashboard.stripe.com/test/logs/req_oGnh2jb2cpbV41
Sorry if that isn't clear, if there is a schedule it will update the schedule when working in the UI. To update just the sub, I'd have to update through the API
tired wharf
And your goal is to charge the customer immediately for the remaining time for a quantity of 2 at the $1575 price and create a proration for the unused time at the $1500 price for a quantity of 1?
vivid spade
Preferably, the additional quantity itself would be charged at the 1575 price.
But yea, the proration should be 1500 since that's all the customer has paid for at this point
tired wharf
Got it. Give me a few more minutes to dig into this
vivid spade
Of course, thanks for helping
tired wharf
Okay, let's go back to that original scenario:
In December subscription is updated to price Y
In April (before the renewal period), subscription is prorated to increase quantity by 1, to 3.
In December, you should make the price update to price Y and pass proration_behavior: always_invoice. this will credit the customer for unused time on price X and debit the customer for remaining time on price Y
In April, you should make the quantity update with proration_behavior: always_invoice
It's not possible to make a single invoice with prorations in April that contains a credit for unused time quantity 1 with price X and a debit for the remianing time quantity 3 on price Y.
woven wyvernBOT
vivid spade
Reviewing now. One moment please
In December, you should make the price update to price Y and pass proration_behavior: always_invoice. this will credit the customer for unused time on price X and debit the customer for remaining time on price Y
I don't actually think this is what we want. Wouldn't this have the effect of charging the customer immediately for the price increase for the period they've already paid for?
The way we conceptualize this, the customer has already paid from July 2024-July 2025. So we can't change the amount charged for that period. That'd violate our contracts with our customers.
Instead, we want to raise the price for the term starting July 2025 and require any prorations, quotes, pre-bills, etc during the 2024 to now be at the increased price.
lyric needle
Hi @vivid spade I'm taking over this thread. Give me a sec to go through th past conversations.
vivid spade
In April, you should make the quantity update with proration_behavior: always_invoice. It's not possible to make a single invoice with prorations in April that contains a credit for unused time quantity 1 with price X and a debit for the remianing time quantity 3 on price Y.
Also, I thought that always_invoice was the default behaviour. Which is what the UI did when it updated the subscription quantity. The issue isn't that it created a proration, it was that it calculated it incorrectly
@lyric needle thanks for the assist. Feel free to @ me again when you're ready! I'll be around, but it's now after hours for me
lyric needle
Can you tell me what makes you think the proration is calculated incorrectly?
vivid spade
Sure, it's using the 1575 price as the basis for the unnused time refund, right? But the customer never paid at that 1575 price, so we're actually deducting too much.
lyric needle
Can you share with me the invoice ID?
lyric needle
Is your question about why there's an unused time line item that credit USD 1186.63 to the invoice?
vivid spade
Yes, about that amount specifically. If you look at the line item, the amount is based on the 1575 price
When the customer only ever actually paid at the 1500 price. Since the change was done with proration_behavior=none. So, we'd expect to calculate prorations on the basis of the 1500 price, not the 1575 price
lyric needle
https://dashboard.stripe.com/test/logs/req_oGnh2jb2cpbV41 based on the request, you set proration_behavior to "always_invoice", not "none"
vivid spade
Not for the proration event, but when I updated the price
lyric needle
What' the ID of request that you made to update the price?
vivid spade
Hmm, maybe I'm mistaken, I don't see none on their. Let me try again
there is another example ^^
Let me get you the logs
Changing the price:
https://dashboard.stripe.com/test/logs/req_9jplP8S2s9Kkn0
Updating the quantity:
Although looking closer, I wonder if this wouldn't satisfy our needs after all. Since the outcome of invoice in_1P1HcvKVm4WHjNVw51F1k7A2 is roughly ~1575 which is what we'd want.
Since, it's calculating both the unnused portion and all the newly increased prorated quantity at the new price, the net effect is charging for the new price for the additional seat
lyric needle
Perhaps you can tell me what you want to achieve here?