If you run an affiliate program on Stripe subscriptions, you pay commission when an invoice gets paid. The part that quietly breaks is what happens when a renewal that already earned someone a commission stops being paid.
Most implementations reverse on the wrong event. I had the shape of this wrong myself until I sat down with the retry docs and read what actually fires.
The event everyone reverses on is the wrong one
invoice.payment_failed looks like the obvious trigger. Stripe describes it as: "Occurs whenever an invoice payment attempt fails, due to either a declined payment, including soft decline, or to the lack of a stored payment method."
Attempt is the load-bearing word. It fires once per attempt, and the Smart Retries docs say "The recommended default setting is 8 tries within 2 weeks." So a single doomed invoice can fire that event eight times. If your handler reverses a commission each time, you have clawed back the same commission eight times.
