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:
- An invoice is created -
invoice.created
- The subscription billing period is updated -
customer.subscription.updated
- After an hour (giving you time to add any additional charges) Stripe attempts to charge the customer.
- 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.
- Find the customer subscription using the Stripe identifier (included in the event payload).
- Retrieve the subscription details from the Stripe API.
- Update our subscription's
CurrentPeriodStart
andCurrentPeriodEnd
with the Stripe subscription'speriod_start
andperiod_end
. - Create a customer invoice using the details from the Stripe event.