#enraged-camel_best-practices
jolly dragonBOT
👋 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/1324782730784805027
📝 Have more to share? Add more details, code, screenshots, videos, etc. below.
faint tree
Hello! Paying the most recent Invoice will bring the Subscription back to active status. See here for details: https://docs.stripe.com/billing/subscriptions/overview#unpaid-subscriptions
maiden kindle
What's the easiest way to get the most recent invoice via the API? List all invoices, then sort them in memory based on invoice date?
faint tree
No, the Subscription has a latest_invoice property: https://docs.stripe.com/api/subscriptions/object#subscription_object-latest_invoice
maiden kindle
Does it need to be finalized first? I assume not
faint tree
Not sure I understand the question. Can you provide more details?
maiden kindle
I remember something along the lines of draft invoices needing to be finalized before they can be paid
There's a /finalize endpoint on invoices
faint tree
Yes, that's correct, Invoices do need to be finalized before they can be paid.
maiden kindle
So I need to fetch the subscription with the latest_invoice prop expanded, then finalize that invoice, then pay it
In order to reactivate the subscription
faint tree
Yes, if it's not already finalized.
maiden kindle
Hmm
faint tree
How else can I help? Have you tried this in test mode to see how it behaves?
maiden kindle
I'm implementing it at the moment, but there are a lot of statuses and edge cases I'm having to deal with. In this particular scenario, I don't understand the "if it's not already finalized" bit. What would make it "already finalized"?
Or rather, under what conditions would an expired subscription's latest invoice NOT be finalized?
faint tree
When a new Subscription period comes around the Subscription creates an Invoice in draft status and waits about an hour for you to make changes to it before automatically finalizing it.
So if you're doing this in that hour window, it'll be in draft.
See here for details: https://docs.stripe.com/billing/subscriptions/overview#invoice-lifecycle
maiden kindle
But we're talking about an expired subscription, where Stripe has attempted to pay the invoice X times (based on our settings) before finally setting the subscription status to unpaid. So in this scenario, the invoice will be well past that 1 hour window, meaning that in our case, the latest_invoice on an expired subscription should never be in draft status. Or did I misunderstand?
faint tree
That's correct, but I'm talking about when the Subscription generates the next Invoice.
The Subscription will continue to generate new Invoices.
maiden kindle
Stripe keeps generating invoices for unpaid subscriptions... I see
faint tree
Yeah. You can, for example, have a Subscription sitting there with three unpaid Invoices. Paying the most recent one will reactivate the Subscription. The other two unpaid Invoices can then also be paid if you wish, or voided, or whatever makes sense for your situation.
This gives you the flexibility to handle longer unpaid lengths of time however you want, because the Invoices will be there waiting for you to action if you need/want them.
maiden kindle
Can we just leave them as is, i.e. Failed?
faint tree
But one an Invoice isn't the latest, paying it (or not) won't impact the Subscription further.
You can, sure.
maiden kindle
Does calling the /finalize endpoint for a non-draft invoice generate an error?
faint tree
I encourage you to give all of this a try in test mode to see exactly how it works. You can use Test Clocks to advance time so you don't have to wait in realtime for Subscription periods to elapse: https://docs.stripe.com/billing/testing/test-clocks
Yeah, I think it does.
maiden kindle
Yeah, I've been using test clocks
They are super annoying though, because deleting the test clock cancels the subscription
I would expect a "simulation" to simply revert all related objects to original status when the simulation ends
Oh well
Maybe a feature request 🙂
faint tree
I can flag it internally if you want, but I'm pretty sure the design isn't going to change. It would be impractical to somehow revert the objects in a Test Clock back to the present time.
maiden kindle
Probably not a battle worth fighting. I'm sure the system was designed the way it was for good reasons
It's just not very practical because there's no way to uncancel subscriptions, so every time we test it we need to sign up with a new account in our system and go through the whole song and dance again, if that makes sense
faint tree
Most people handle that by writing a script that gets them to a known good starting point. Then they can run the script at any point to create a new Test Clock, new Customer, new Subscription, etc. and then start testing from there.
maiden kindle
Got it
So to summarize: to make an unpaid subscription active again, we first fetch the subscription with the latest_invoice prop expanded. We check the status on that invoice. If draft, we finalize it first before paying. Otherwise we pay it right away.
faint tree
Yep.
maiden kindle
Can you explain this part from your link a bit more?
Turn automatic collection back on by setting auto advance to true on draft invoices.
I clicked the link and it took me to https://docs.stripe.com/api/invoices/update#update_invoice-auto_advance
However, this appears to be a property on the invoice itself. If we're already finalizing and manually paying the invoice, why do we need to set auto_advance on the invoice?
faint tree
If you're handling everything manually you don't need to turn auto advance on. See here: https://docs.stripe.com/invoicing/integration/automatic-advancement-collection#toggle-auto-advance
maiden kindle
Nice. Thanks for confirming! I think I have enough info to get unblocked for now. Happy New Year!