Dev Orion

[floral kettle]

I am not from the Stripe guys, but maybe you are missing some event

[pastel plaza]

¯_(ツ)_/¯

i've been talking to them, and they seem to think i have the correct events

[floral kettle]

let me check something in mines

[pastel plaza]

hey thanks

[floral kettle]

check these out

[pastel plaza]

i'll try a couple of those. thanks

[floral kettle]

also check the webhook be properly configured for your testing env

you are welcome my friend

[pastel plaza]

i'm confident it's properly configured in the testing environment. the endpoint secret matches as well

[muted holly]

Wait, so you're listening for subscription_schedule events, but you don't mention creating a Subscription Schedule or cancelling a Subscription Schedule. Are you making calls to do things with Subscription Schedules? Or are you simply cancelling the Subscription?

[pastel plaza]

only doing things with the Subscription. i'm using the events that Stripe's ISD told me to use for my case

still, i figured the customer.subscription.trial_will_end event would fire

ha ok. apparently, canceling a free trial results in a customer.subscription.updated event firing. but why not the "trial_will_end" or "canceled" events? that doesn't make sense to me. what am i missing?

[muted holly]

So those events won't fire unless you're doing something with Subscription Schedules. You should be listening for the events that kanohian mentioned

customer.subscription.created
customer.subscription.updated
customer.subscription.deleted

[pastel plaza]

why wouldn't customer.subscription.trial_will_end fire if i cancel a free trial? the docs strongly suggest that it should: https://stripe.com/docs/api/events/types#event_types-customer.subscription.trial_will_end

or am i supposed to look at the canceled_at field in the "update" object?

and why wouldn't subscription_schedule.canceled fire? is that only for non-trial subscriptions?

[muted holly]

Did you cancel the trial using trial_end=now?

[pastel plaza]

i canceled via a billing management session, i.e. via a session opened up in Stripe's portal, triggered by my site

i guess i can infer that by default that trial_end=now isn't set for the portal? if that's the case, where can that be changed?

[muted holly]

What events are you seeing for the Subscription? You can view the event in the Stripe Dashboard at the Subscription level by either going to the Subscription view or by filtering on the Subscription ID: https://dashboard.stripe.com/test/logs?method[0]=post&method[1]=delete&direction[0]=connect_in&direction[1]=self

The above view is in test mode, so if it's a live mode subscription, then you'll need to toggle test mode off before filtering in the same view

[pastel plaza]

i'm in test mode, and that log only shows webhook modification calls and billing portal sessions. in fact, if i clear the filters, i don't see anything related to any subscriptions:

[muted holly]

You need to get the Subscription ID and plug it into the search form

Go to this view and locate the Subscription you've been testing with: https://dashboard.stripe.com/test/subscriptions

The ID will be in the top right side of the Subscription view

[pastel plaza]

ok. the logs show no API calls for the subscription i just canceled, but clicking on the subscription itself and then its "Events" section shows the customer.subscription.updated event for today and that's all.

[muted holly]

Yeah, so it sounds like all modifications are being done via the Customer Billing Portal, so the logs won't be helpful. This seems like expected behavior. Which events (aside from customer.subscription.updated) are you expecting?

[pastel plaza]

for now, i just need to know when a subscription is canceled (be it as part of a free trial or not), if a free trial elapses, or if payment fails.

we were told to use:

customer.subscription.trial_will_end, payment_intent.payment_failed, subscription_schedule.aborted, and subscription_schedule.canceled

and based on the testing we've done, it isn't at all clear which events to expect to address our use cases

we still have to test paying for a subscription and then canceling, etc., but we want to get the free trial stuff straight first

[muted holly]

Okay, so if you're not using Subscription Schedules, then you should ignore what you were told. I'm not sure why someone would recommend that if you're not doing anything with Subscription Schedules. Now, let's look at each individual situation:

subscription is canceled (be it as part of a free trial or not)
If you actual cancelling the Subscription (not just ending the trial) you will listen for customer.subscription.deleted

if a free trial elapses
I assume you're talking about when a trial ends. In this case, you would listen for customer.subscription.updated

or if payment fails
If a payment on a Subscription fails, you will be notified by the event invoice.payment_failed

Honestly, your best resource for getting information about this is here: https://stripe.com/docs/billing/subscriptions/webhooks#payment-failures

You should read that article thoroughly

[pastel plaza]

I assume you're talking about when a trial ends. In this case, you would listen for customer.subscription.updated

...if it ends by means of just elapsing with no user input, is it still that same event? or what if the user puts in payment details at the end of the trial but they're incorrect?

and yeah, i've looked through the page you linked. it isn't clear how to handle trials ending/being canceled. and it isn't at all clear which event(s) are fired for a canceled subscription (just when it "ends"). https://stripe.com/docs/billing/subscriptions/webhooks#state-changes mentions cancellations, but doesn't explicitly state which event(s) to listen to

[muted holly]

...if it ends by means of just elapsing with no user input, is it still that same event? or what if the user puts in payment details at the end of the trial but they're incorrect?
From our docs on the event: https://stripe.com/docs/api/events/types#event_types-customer.subscription.updated
Occurs whenever a subscription changes (e.g., switching from one plan to another, or changing the status from **trial** to **active**). If a Subscription's status updates, customer.subscription.updated will occur. That happens with or without user/customer intervention.

On cancellation, the Subscription fires customer.subscription.deleted. This fact is only called out in the API reference: https://stripe.com/docs/api/events/types#event_types-customer.subscription.deleted , which can definitely be confusing if you don't know to look there or if you don't have a testing environment set up to view which events are triggered

Occurs whenever a customer’s subscription ends.

[pastel plaza]

ok, for this event, i need to check the status enum for unpaid, canceled, and incomplete_expired?

can i also infer that you're saying i only need to listen for two events? namely, customer.subscription.updated and customer.subscription.deleted?

(to cover my use cases, anyway)

[knotty dune]

@pastel plaza I'm stepping in for @muted holly here -- the result there depends on your account settings for how to handle overdue/unpaid invoices for subscriptions

incomplete_expired is specific to new subscriptions with initial payments that are never completed

as far as i know its not used in any other scenarios

[pastel plaza]

sounds like a case to be covered

[knotty dune]

Yes, but its fairly different from a lapsed payment on a previously active subscription (ie, one where there was a past payment)

[pastel plaza]

honestly, the stakeholder in this only cares whether a person is currently subscribed, or not

[knotty dune]

Fair enough

[pastel plaza]

so, with that said, is it sufficient to only subscribe to customer.subscription.updated and customer.subscription.deleted in order to cover the stakeholders "concern"?

[knotty dune]

Mostly yes, with the caveat that depend on your account settings and how you consider whether a person is subscribed

eg: you might not use any settings to mark the sub unpaid or cancel it

but they can have payment failures if the recurring payment fails

is that person subscribed?

The subscription will still be active, but they may have one or more invoices with failed payments

[pastel plaza]

got it. but we can make that determination by examining the status enum in the customer.subscription.updated event, no?

[knotty dune]

Only if your settings will eventually update the status -- that's not always used

https://dashboard.stripe.com/settings/billing/automatic > "Manage failed payments"

The manual way to track this would be listening for invoice.payment_failed eg

And then deciding what to do about recovering that payment and/or cancelling the subscription

[pastel plaza]

ah ha. so the "manual way" would be to listen for that event, and each time a payment attempt fails, we receive it and can decide what to do, e.g. wait to hear for 3 of them before taking action

and thank you for this, btw

[knotty dune]

If you used automatic retries, something like that, yea. Or you can kick off your own dunning/recovery flow that terminates in a cancelation (for example) if you cannot collect payment in the time you decide.

[pastel plaza]

makes sense. i think this should be enough to get us off the ground, but i'll talk to the stakeholder about all this. to start, i think they'd just want to know if someone is subscribed or not, and if payment fails for any reason, then it gets canceled, which i understand can be configured via the link you gave. this means that 90-95%+ of the cases we need to deal with should be covered by the two events named above

[knotty dune]

Yep that sounds reasonable!

[pastel plaza]

awesome. thank you again 🙂

[knotty dune]

NP! Good luck with it 👍

[pastel plaza]

cheers