#neha_best-practices
prime badgerBOT
đź‘‹ 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/1215529934580351056
đź“ť Have more to share? Add more details, code, screenshots, videos, etc. below.
wispy ginkgoBOT
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.
- neha_docs, 3 hours ago, 26 messages
- neha_webhooks, 6 hours ago, 66 messages
- neha_unexpected, 8 hours ago, 73 messages
- neha_best-practices, 1 day ago, 47 messages
fringe thistle
I got cut off. Basically, imagine you start with 50 credits for $10. Then, mid month, you upgrade to a plan with 150 for $20. As it’s the middle of the month, you only receive half of the difference a.k.a. 50 credits, and you only pay half of the difference a.k.a. five dollars.
Conversely, if you downgrade, I don’t want this to be processed until the end of the Current period at which point you’d pay the regular price for the lesser subscription
So my idea was to create a hypothetical invoice so that I could display the proration to the user… but then how do I actually have the user pay that invoice?
I was also thinking about attaching metadata to the invoice detailing the proration amounts so that the web hook could allocate accordingly once the invoice was paid
Because basically my invoice.paid Webhook is doing the credit allocation and I want to make sure that it’s prorated when applicable and the only way I could think to do this was through metadata
small quartz
hello! Stripe will prorate the amount paid by the customer. You'll need to prorate the credits yourself though.
You can read more about upgrading a Subscription here : https://stripe.com/docs/billing/subscriptions/upgrade-downgrade
If you only want to downgrade at the end of the current period, you'll want to look into Subscription Schedules instead : https://docs.stripe.com/billing/subscriptions/subscription-schedules where you would create a Subscription Schedule for an existing Subscription, then schedule the new Price to start on the next billing cycle
in case you haven't seen this yet, you can use test clocks to mimic the passing of time : https://stripe.com/docs/billing/testing/test-clocks
fringe thistle
I’ve read through all the docs, but I don’t understand how to best put it together
If my invoice.paid, Webhook is doing the allocation then it makes sense to add the credit proration there, right?
As a piece of metadata
Or are you recommending that I somehow recalculate the proration in the invoice.paid web hook?
The reason I was on the track of hypothetical invoices was because I did think it would be nice to show the user a summary before they confirmed the charge
small quartz
lets take this step by step and talk about upgrading first - so if you upgrade now, Stripe will calculate the prorations for you. Do you need any further clarifications on this part?
small quartz
if you don't have any questions about upgrading then we'll move on to downgrading
fringe thistle
No, that’s not the complete answer
Because I’m not using the customer portal, I need to show a message to the user explaining how much they will be charged, and how many prorated credits they will receive
For this, I was going to use a hypothetical invoice
So, for example, the hypothetical invoice says that the user will be charged five dollars and receive 50 credits
Now, when I do the subscription update, I pass in the same date so that the dollar value is correct
How do I also pass in the prorated credit amount as a piece of metadata such that when the invoice paid hook is called I can retrieve that metadata
Or would you suggest a different approach?
Does that make sense? The invoice.paid hook is the “allocator”. It needs to know if there’s a special prorated credit grant that will override the default grant
small quartz
what's a hypothetical invoice? Are we talking about a Stripe Invoice?
fringe thistle
Yes, that’s the documentation that I linked in the original ticket
It says you can create a hypothetical invoice for the purposes of displaying expected charges to a user
But that this hypothetical invoice cannot be paid
I guess maybe something else I could do is take the date of the invoice and compare it to the subscription start and end date, prorate on the fly in the webhook.
small quartz
maybe i'm missing something in the docs, but i don't see anywhere that mentions the word hypothetical. In any case, are you actually referring to an Upcoming Invoice : https://docs.stripe.com/api/invoices/upcoming?
fringe thistle
Yes sorry
The invoice you make that’s just a preview
That cannot be paid because it’s not real
small quartz
then yes, you can use upcoming invoice for that, pass the same date when upgrading the Subscription, and include the prorated credit amount as metadata
fringe thistle
What object do I pass the prorated credit on?
The subscription or the invoice
Because it’s just temporary metadata I wouldn’t want it to live on the subscription forever
That’s why it’s more suitable for the invoice
Or is it in the schedule?
On the phase?
Set of key-value pairs that you can attach to a phase. Metadata on a schedule’s phase will update the underlying subscription’s metadata when the phase is entered. Updating the underlying subscription’s metadata directly will not affect the current phase’s metadata.
small quartz
we're not talking about subscriptions schedules yet.
It's up to you whether you want to pass it in the Subscription or in the Invoice when it's generated, each has it's own pros/cons. For example, if you pass it into the Subscription, you'll need to remove it later after processing the credits. If you want to pass it into the Invoice, you will need to listen for the invoice.created webhook and check the billing_reason : https://stripe.com/docs/api/invoices/object#invoice_object-billing_reason to validate that it's a subscription update and it's for an upgrade.
You may want to consider https://docs.stripe.com/billing/subscriptions/pending-updates#canceling-changing
fringe thistle
So you’re suggesting that I make a real invoice
And then, if the user backs out, voiding it
small quartz
no, i didn't suggest that you make a real invoice
fringe thistle
Okay so the step by step so far is
- Use invoice api to generate an invoice (real or fake?)
small quartz
passing in the metadata is when the customer is ready to upgrade the Subscription. An Invoice for the upgrade is definitely generated
fringe thistle
- Then make a change to the subscription schedule so that the user is immediately on the new plan. This will generate in invoice(?) and pro rate the charge
And maybe put the credit amount somewhere in there as metadata
- Listen for invoice.paid, get the metadata regarding the credit, process accordingly(?)
small quartz
again, we're not talking about Subscription Schedules
You won't use Subscription Schedules for upgrades
fringe thistle
Oh
So how do you upgrade the user and generate an invoice. Just change the line items on the subscription?
small quartz
https://docs.stripe.com/billing/subscriptions/upgrade-downgrade#changing - Have you gone through this doc which I shared earlier?
fringe thistle
Okay
So simply updating the sub with the new price ID is sufficient
To charge the customer the pro rated amount
small quartz
- Generate an upcoming invoice for the customer to preview
- If the customer decides to go ahead, you ideally update the subscription to the new Price and with
proration_date. You should go through https://docs.stripe.com/billing/subscriptions/pending-updates and understand why you should usepayment_behavior=pending_if_incomplete
fringe thistle
OK got it. Using the doc you sent, I can make sure that the update doesn’t go through ahead of the payment.
But is the invoice I generate actually used for the subscription update?
Because it seems like an artifact for display purposes only
small quartz
But is the invoice I generate actually used for the subscription update? - are you referring to the Upcoming Invoice API?
fringe thistle
Yeah, just reading through your step one and two
Step one was making an invoice
Upcoming invoice
small quartz
Upcoming Invoice does not generate an actual Invoice. You need to display those details from the Upcoming Invoice object in your own site
it's only in step 2 that an actual Invoice is generated
fringe thistle
So that’s not where I would put the metadata. In your example, the meta-data would go on the subscription object during the update process. Correct?
Because, presumably, if the invoice is generated automatically by stripe following the subscription update, I won’t be able to catch it fast enough to add the meta-data
small quartz
In your example, the meta-data would go on the subscription object during the update process. Correct?
It's up to you whether you want to pass it in the Subscription or in the actual Invoice when it's generated. You can add it to the Invoice after it's generated.
fringe thistle
But if the invoice is generated and paid within seconds, isn’t there a chance I don’t catch it?
Before the invoice.paid webhook is called
Question: if the payment fails, will the proration be according to when the invoice was generated, or when the pay succeeded?
small quartz
hrm, you can't pass in metadata with the payment_behavior="pending_if_incomplete" - so i guess if you want to update it on the Subscription, you'll need to make two requests :
- update the subscription metadata first
- update the Subscription to the new Price
if the invoice is generated and paid within seconds, isn’t there a chance I don’t catch it?
yes, you wouldn't be able to update the Invoice's metadata before it's paid
Question: if the payment fails, will the proration be according to when the invoice was generated, or when the pay succeeded?
what proration are you talking about if the payment fails?
fringe thistle
Like if I’m supposed to upgrade and pay $10 today, but my payment doesn’t go through for two days, will I pay less than $10 or will I pay $10?
Is the invoice amount fixed?
Or is the proration real time
Because another possibility I’m imagining is: don’t pass any metadata, and instead, use the invoice timestamp alongside the subscription, timestamp to determine whether the credits should be prorated. But I can see people being mad if they paid the full $10, their payment was delayed, and as a result they got less than their 50 promised credits, or whatever
small quartz
https://docs.stripe.com/billing/subscriptions/pending-updates#canceling-changing
If you want to change the values for a pending update, update the subscription with the new values. This attempts another payment. If the payment succeeds, the most recent values are applied and the outdated values are discarded. If payment fails, a new pending update replaces the existing one and the expiry date is recomputed from the current time.
fringe thistle
I read that, but I didn’t understand it
What’s the default behavior if I’m not calling the API
small quartz
which implies that the customer will pay the old proration amount, unless you update the subscription with new values
fringe thistle
OK that makes sense. I think I have enough to go off of for the upgrade flow.
And I guess to wrap up with downgrades: for this, I’m assuming I just make a schedule?
Instead of calling subscription.update, I call schedule.update
small quartz
No, 1) you make a request to create a schedule for an existing Subscription, 2) then make another request to update the newly Subscription Schedule to change the Price in the future
fringe thistle
Ok got it
Last question: are there any good examples of credit based systems in the stripe documentation? I feel like I’m reinventing the wheel and it gives me pause about the design of my system
Which is simply prorating my internal currency on upgrade, and disallowing immediate downgrade, which does seem common based on Internet searches
The latter not the former
small quartz
we don't have any examples of credit based systems since that's something that you would manage yourself. Rather than credits/tokens, maybe it'll be a lot easier to just manage based off cash amounts
fringe thistle
As in, use the cash paid to indicate the credit granted?
small quartz
yep, but i don't know if your business model can handle cents though, cause proration is to the second, and the customer may likely end up with an "odd" amount
fringe thistle
So, just to be clear, you’re saying that I can take the prorated charge, do some simple math, and come out the other end with the number of credits
As opposed to figuring out the prorated credits on my own
Like if the user paid $10, and the Delta between the plans was $20 then I can assume 50% should be granted
Basically taking the prorated to charge as the source of truth? as opposed to any timestamps on the subscription or the invoice
small quartz
uh no, what i was suggesting is that for example if a customers needs 1 credit to do something, and 1 credit costs $5, maybe instead of charging in credits, why not put it as the customer needs $5 to do something