Stripe Webhook events Renewal of subscription

Question

I am using STRIPE for credit card payments in my Asp.net Application. Application have an monthly subscription plan. First time when user subscribe the webhook event 'customer.subscription.created' fired. my question is what happened which events will be fired when next month subscription is renewed ? Can anyone tell me the flow on subscription renewal webhook events?

Thanks

Answer 1

The webhook 'invoice.payment_succeeded' actually does distinguish between the first charge of a new subscription and subsequent renewal charges.

The webhook sends an invoice object, which includes 'billing_reason' - the possible values of which are noted in the Stripe Docs - The Invoice object:

billing_reason (string) "Indicates the reason why the invoice was created. subscription_cycle indicates an invoice created by a subscription advancing into a new period. subscription_create indicates an invoice created due to creating a subscription. subscription_update indicates an invoice created due to updating a subscription. subscription is set for all old invoices to indicate either a change to a subscription or a period advancement. manual is set for all invoices unrelated to a subscription (for example: created via the invoice editor). The upcoming value is reserved for simulated invoices per the upcoming invoice endpoint."

If billing_reason == 'subscription_cycle' the webhook is for a subscription renewal.

If billing_reason == 'subscription_create' the webhook is for a brand new subscription.

Answer 2

As well as customer.subscription.created you will also receive a invoice.created followed by invoice.payment_succeeded (or invoice.payment_failed)

From the documentation:

If you are using webhooks, Stripe will wait one hour after they have all succeeded to attempt to pay the invoice; the only exception here is on the first invoice, which gets created and paid immediately when you subscribe a customer to a plan.

So, this means, invoice.created event will also fire next month.
Stripe will then wait an hour before charging the customers card, then firing charge.succeeded (if the charge is succeeded) or charge.failed (if the charge fails)

The hour wait is to allow invoice items to be added to the invoice if you so wish.

See my answer on this question for more information on why you might need to do that...

Answer 3

Renewing Subscriptions:

When a customer's subscription is renewed in Stripe a number of things happen, each with a corresponding event:

1. An invoice is created - invoice.created
2. The subscription billing period is updated - customer.subscription.updated
3. After an hour (giving you time to add any additional charges) Stripe attempts to charge the customer.
4. Given payment is successful an invoice.payment_succeeded event is raised.

The way to handle these events within your own application is to register a webhook; a HTTP endpoint that Stripe will send details of the event to.

1. Find the customer subscription using the Stripe identifier (included in the event payload).
2. Retrieve the subscription details from the Stripe API.
3. Update our subscription's CurrentPeriodStart and CurrentPeriodEnd with the Stripe subscription's period_start and period_end.
4. Create a customer invoice using the details from the Stripe event.

Answer 4

You would want to watch for a invoice.payment_succeeded event:

Have a look at: https://stripe.com/docs/api#event_types

This event is triggered any time an invoice is paid. A charge.succeeded event also occurs, but the difference is that invoice.payment_succeeded only occurs for payments on invoices, whereas charge.succeeded also occurs for standalone charges.

There is no event distinction between the first charge on a subscription and a recurring one, although the logic you store on your end (e.g., when the subscription was created, when it expires, etc.) should help you disambiguate them.