Stripe subscription events webhooks are not clear

user_14281301 0
Viewed 1335

Say I am letting customers subscribe to a service, as I see it there are 2 events that I need to know about :

  1. The current charge succeeded or failed, so I can congratulate him for joining in.
  2. every next charge (every month) succeeded or failed.

Stripe have too many events, and it's hard to know which one of them to listen to :

invoice.paid - "Occurs whenever an invoice payment attempt succeeds"

charge.succeeded - "occures when a new charge was created" (so what's the difference??)

invoice.payment_succeeded - "Occurs whenever an invoice payment attempt succeeds."

customer.subscription.created - "Occurs whenever a customer is signed up for a new plan."

Now I am aware that a few events can happen for a single API call, but,

What should a developer listen to in order to know that his user successfully subscribed, or failed ? how invoice.paid is different than charge.succeeded ? and how invoice.payment_succeeded is different from those ?

It is too messy, I just need to get a yes or no. I read the API https://stripe.com/docs/api/events/types

stripe-payments
1 Answers

It comes down to what you want to listen for.

charge.succeeded will trigger when an invoice is successfully paid, but it'll also trigger for one-off payments.

invoice.paid will trigger when an invoice is paid but will also trigger if you mark the invoice as paid out of band (e.g. someone pays you in cash)

invoice.payment_succeeded is the same as invoice.paid, but won't trigger if you mark the invoice as paid out of band. If you don't anticipate ever accepting out of band payments, then consider using this event.

customer.subscription.created will trigger when a new subscription is created, which isn't the same as the first invoice being paid (e.g. you can create a subscription with a trial period that won't trigger an invoice paid event immediately).

If your business only works with subscriptions (and not one-off payments) and you don't particularly care about the invoice data, use charge.succeeded. If you use both then it's useful to listen to both events to distinguish between the two.

In your case, you probably only want to listen to invoice.payment_succeeded. When you get the invoice, look at the billing_reason field: https://stripe.com/docs/api/invoices/object#invoice_object-billing_reason

If it's set to subscription_create, then send your congratulatory email. If it's subscription_cycle, then it's because the subscription entered a new billing cycle and the payment succeeded.

user_17376580
Related