My use-case is that whenever I have a trial subscription, once the trial ends and the user has no payment method on stripe, I simply want to cancel the subscription instead of generating an invoice. Is there a way to configure this on Stripe or would it need an external task to run each day and do this for me?
A new invoice will always be generated when a payment is due, and Stripe will try to charge the customer for it. If you want to avoid it, you will need to check if the customer has a PaymentMethod on the last day of the trial, and update the Subscription to set the cancel_at_period_end property to true.
Alternatively, you can listen to customer.subscription.updated webhook event - when the status changes from trialing to active and the customer does not have a PaymentMethod, you can cancel the Subscription manually. In this case, however, a draft Invoice will still be created, but automatic collection will be stopped - the invoice will stay as a draft and will never be finalized.
Related
I have a subscription whose collection_method has been set to send_invoice.
I can't figure out the correct webhook event when the invoice for the subscription is sent to the customer each month but the customer didn't pay it or the payment made by the customer failed.
I think it is invoice.payment_failed but I am not sure whether that applies when the customer doesn't pay the invoice situation too.
Can anyone help me out here?
The invoice.payment_failed is the right one to indicate a payment failure, but the case of customer not paying the invoice is a bit different. It depends on your settings to handle the invoice and/or subscription after payment failures or time past due.
If you choose to have the invoices marked uncollectible, you get the invoice.marked_uncollectible event. If there is a related subscription and you chose to modify it, you'd receive a customer.subscription.updated event (ref) with the new status.
Say I am letting customers subscribe to a service, as I see it there are 2 events that I need to know about :
The current charge succeeded or failed, so I can congratulate him for joining in.
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
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.
I am creating a subscription from a Stripe checkout session. After a customer goes through the checkout session, an invoice is then created and triggers invoice.created. On this event, I have a webhook that is attempting to update the invoice, however, by the time it gets here, the invoice is already set to finalized and I cannot update it.
How do I get around this?
I contacted Stripe support and their recommendation (for our situation) is to give the subscription a trial period and then set the trial end to a few minutes from that point in time so that the invoice can go through each event properly.
I am using stripe for a subscription based project and recently found out that you can subscribe without the user requiring payment information with a trial period.
How does stripe handle the user once the trial period ends but didn't any payment information?
When I look at customers it says that there isn't any default source.
At the end of the trial period, the Subscription would renew its billing cycle. This would make the Subscription move to status: "active" and send customer.subscription.updated. A new Invoice would also be created. This would send the invoice.created event.
An hour or two later, the Invoice would be automatically finalized and Stripe would attempt to pay it. The payment would fail since the Customer has no payment method attached. This would send an invoice.payment_failed event. The Invoice would be retried multiple times as documented here. Stripe can even send emails to your Customer asking them to add/update their card.
If all payment retries fail, the Subscription would then be canceled automatically.
What event should my webhook look for in order to update a customer's subscription in my database? I would assume customer.subscription.updated as it contains the current_period_start and current_period_end items. However, my concern is that customer.subscription.updated is apparently fired an hour or so before invoice.payment_succeeded is fired. I wouldn't want to update a customer's subscription if the payment then failed an hour later.
As duck stated in his/her comment, I think the best way to update a subscription if the payment of the invoice failed or succeeded is to listen to these events:
invoice.payment_succeeded: Occurs whenever an invoice payment attempt succeeds.
invoice.payment_failed: Occurs whenever an invoice payment attempt fails, due either to a declined payment or to the lack of a stored payment method.
Actually this is the way I handle things in production, and it is very effective. I would recommend the Stripe documentation's article Billing Lifecycle and Events, especially the section The subscription lifecycle:
After this first invoice, the following cycle of events repeats every
billing period:
When the subscription approaches its renewal date, an invoice.upcoming event is sent.
When the subscription period elapses, an invoice.created event is sent, indicating the creation of a draft invoice.
About an hour after the invoice is created, it is finalized (changes are no longer permitted), and an invoice.finalized event is
sent. A charge is attempted, and a charge.succeeded event is sent to
indicate that the payment was successful.
An invoice.payment_succeeded event is sent to indicate that the invoice was marked paid.