#Paul Han
sharp jewel
formal folio
Hello! Typically this kind of thing is handled by getting the customer to pay both outstanding Invoices. You can, however, void the old Invoice and add a new line item to the new Invoice with the additional amount.
opaque axle
is there a recommended way to retrieve the failed invoice for a subscription?
formal folio
You can list Invoices by both subscription and by status: https://stripe.com/docs/api/invoices/list
opaque axle
ah thank you so much
May I also ask - do you know what the default retry behavior is when auto_advance is set to false on a subscription?
retry meaning retry for failed payments
formal folio
There is no default, really. The behavior is controlled by your settings in the Dashboard here: https://dashboard.stripe.com/settings/billing/automatic
opaque axle
I guess whats confusing is that I only have the option to set Smart Retry OR a custom schedule... so if I have "Smart Retry" selected but a subscription is not set to auto_advance it will not use Smart Retry...
so i'm not sure in that scenario what would happen
formal folio
Not sure I understand... I think there might be a misunderstanding somewhere. Can you provide more details about why you're bringing up auto_advance in relation to these retry settings?
opaque axle
Because here it says that Smart Retry will only work if auto_advance is set to true: https://stripe.com/docs/invoicing/automatic-collection#smart-retries
formal folio
That's correct, but I think you're misunderstanding the custom schedule part. If you have a custom retry schedule configured it will also apply to auto_advance Subscriptions.
Well, I shouldn't say "also" there. It will apply instead, because that's what you've selected.
opaque axle
What if I have Smart Retry selected:
formal folio
Backing up a bit, can you tell me what you're trying to accomplish? We're talking at a very abstract level, and knowing more about your specific use case and goals will help me get you to a more useful answer.
opaque axle
Sure, thank you for asking. I want to send the customer an email asking them to update their payment method if their payment attempt failed n times (probably on the third). But I don't want to use the "Send emails to customers to update failed card payment methods" setting because I only want to send the email for a very specific type of subscription.
In order to do this I want to understand accurately what the retry schedule will look like.
If the retry is going to happen back to back (which it does when testing) I don't want to send the customer emails back to back, maybe only on the third payment
The type of subscription I want to send the emails for does not seem to have auto_advance set to true on the invoices (to be honest I don't fully understand what auto_advance is even doing)
formal folio
Gotcha. What I recommend doing is listening for invoice.payment_failed Events, then look at both the attempt_count and next_payment_attempt properties on the Invoice, which will tell you how many attempts have been made and when the next attempt will be, respectively. You can use that information to determine if you want to send an email or not.
auto_advance is explained in detail here: https://stripe.com/docs/invoicing/integration/automatic-advancement-collection
By looking at those properties in the API you're not going to need to worry about what the Dashboard setting is set to, and your code will be resilient if those settings change.
opaque axle
Thank you that is helpful.
I still do want to understand what will happen if Smart Retry is selected on the setting page, but the Subscription invoices do not have auto_advance set to true on them. Will it default to whatever custom retry schedule is set even when the radio button is not selected/on?
formal folio
No. There wouldn't be retries in that case as I understand the scenario you're describing.
opaque axle
how can I create a subscription so that failed payments automatically retry?
formal folio
The table down at the bottom of that page I linked above might make things clearer: https://stripe.com/docs/invoicing/integration/automatic-advancement-collection#toggle-auto-advance
You would need to enable auto_advance.
opaque axle
hmmm but I dont see that as a field anywhere when creating a Subscription: https://stripe.com/docs/api/subscriptions/create
formal folio
Correct, auto_advance is a property on Invoices, not Subscriptions. What is the collection_method set to on your Subscriptions?
opaque axle
charge_automatically
formal folio
Hm, it should be creating Invoices that have auto_advance enabled then. Can you give me the ID of a specific Subscription or Invoice so I can take a look?
formal folio
This Invoice had auto_advance set to true when it was created. You can see that in the invoice.created Event here: https://dashboard.stripe.com/events/evt_1No48oG9hS6mKJg1nQ5BJbGU
formal folio
No worries!
Once an Invoice is paid auto_advance turns off because there's no further need to automatically advance it... there's nothing to advance it to. 🙂
You can see the status changes in this invoice.updated Event: https://dashboard.stripe.com/events/evt_1No56iG9hS6mKJg1fwYCQLEu
Look at previous_attributes and you can see that auto_advance was turned off when the Invoice was paid.
opaque axle
thank you so much for your help
formal folio
No problem!
opaque axle
If a subscription becomes "past_due" or "unpaid", will it automatically be set back to active once all open invoices are paid?
formal folio
Typically a Subscription goes back to active when the latest outstanding Invoice is paid.
opaque axle
What if the latest is paid but one prior is not?
formal folio
Typically it will become active.
Pay the most recent invoice before its due date to update the status of the subscription to
active.
We assume that previous outstanding Invoices will be handled independently of the Subscription. You can choose to leave them outstanding and collect them, or you can void them. It depends on your use case.
For example, let's say someone subscribes to an online service that grants them access to paid features. If they miss a payment and the Subscription is no longer active you may deny them access to the features until they pay again. If that take a few months before they pay again then you wouldn't want to collect the outstanding Invoices they didn't pay because they didn't have access to the paid features for the periods those Invoices cover.
opaque axle
ah that does make sense
formal folio
However, if you're in a scenario where the subscriber does have access to paid features while the oustanding Invoices pile up, then you would want to collect for the outstanding ones.
Our Subscriptions system kinda defaults to the "paid online services" use case, but we tried to make it adaptable to many other use cases as well.