Stripe Webhook events Renewal of subscription Stripe Webhook events Renewal of subscription asp.net asp.net

Stripe Webhook events Renewal of subscription


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.


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...


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.