I am having a hard time finding the right webhooks in Stripe to use since it seems a lot of get fired off for multiple situations.
So my site sells a few items (like 10) that can be bought as a single purchase or a subscription (you get the item every X days, no SASS jut products). I am using Stripe's Checkout and Portal to handle all subscriptions and single purchase and those parts work great. Person adds stuff to cart, checkouts out, pays, we are all good. The issue is adding an order to our system from the webhook.
Look at this scenario: a person adds 2 single items and 1 subscription to their cart. They checkout and pay. When that happens we had the checkout.session.completed catching the checkout session was completed and we add those items from their cart to an order. The subscription re-ups after "X" Days we would listen for the invoice.payment_succeeded webhook to create a new order in our system. This logic is flawed though since invoice.payment_succeeded is called on the first order too so basically when they checkout our system adds 2 subscription orders: one from the checkout.session.completed and one from the invoice.payment_succeeded. How can we handle this?
What I would like to have is:
1 webhook to know when the checkout is complete and is only called then, which they do: checkout.session.completed
1 webhook that is only called when a subscription is renewed, not also when created, which I cant find.
If they dont have that webhook for subscription renewals only, how can I tell in the "invoice" object is the very first one so I dont do anything on checkout, only create a new order on renewal?
Instead of using invoice.payment_succeeded you should consider using invoice.paid, as it will also fire when you mark an Invoice as paid out-of-band (which won't happen with invoice.payment_succeeded). Both describe an Invoice, so you should be able to switch between them with minimal or no changes to your code.
You're correct that there is no Event specific to renewals for a Subscription only, but you can use the billing_reason property on an Invoice to determine why the Invoice was created. If it's the first Invoice for a new subscription the Invoice will have billing_reason set to subscription_create.
Related
for my subscription based product I want to have a possibility to subscribe and enter payment details at once with stripe and struggle with that with the api.
In https://stripe.com/docs/billing/subscriptions/build-subscriptions?ui=elements I see an option to create a subscription with payment_behavior='default incomplete' and then enter the details to confirm the payment intent. So far so good. However if I create the subscription like that even before the customer confirms payment details stripe already generates an invoice which is not really what I want before final confirmation by customer.
Options I see:
create setupintent, have this filled by customer via elements and then have the customer subscribe. Technically works nicely but for a sales and customer perspective is not good as it has two steps thus probably reduces conversion.
create the subscription in the background before final subscription confirmation by customer and use the clientsecret of it to pass back to browser and then have customer enter his payment data and submit that and finish the setup of subscription and payment info. Technically works - however I realize that when I create the subscription to get the clientsecret to pass to elements before the customer enters his payment data and confirms the subscription the subscription is not only created but an invoice too - which would be really, i.e. an invoice created before customers really confirms the contract
create setupintent and submit it via elements and in metadata of it add the info of product that customers wants so that when the paymentmethod gets created and I get webhook event I do the booking of the product given in metainfo. May however mean the customer gets to success page but the webhook has not notified yet and thus the customer is not really subscrubed at the point in time but gets a success message he is
same as 3 except do not pass info via metadata but via successUrl parameters which refers to and endpoint at my backend which upon being called after setupintent was setup will do the subscription and then redirect to my frontend which shows success page. That seems like a error prone workaround however.
Create a workflow which is a 2 step sign up and asks for paymentinfo, sets that up and then brings customer to a final confirmation page where the submit triggers subscription creation. Seems a bit complicated from a user flow, but so far probably the best option?
Any better options?
Cheers
Tom
ps: Interestingly enough on discord stripe support told me #2 is the way to go - find it hard to believe ...
As far as I know, there isn't a workaround for this unfortunately. It is just how Subscriptions API is designed by Stripe. You can learn more about that here where they talk about "how subscriptions work".
Consider the following course of events:
A user selects one of multiple subscription options on my website and clicks the "pay" button.
They're redirected to the Stripe Checkout page but don't complete the payment yet.
They somehow manage to get back to the page where they select the subscription while keeping the Stripe Checkout page open. (I know this is somewhat contrived but technically possible.)
They choose a different subscription option and click on "pay" again.
A second checkout session is created and another Stripe Checkout page opens.
Now they complete payments on both checkout pages.
How can I prevent this? Is there a way to cancel a checkout session? When I create a checkout session for a subscription, I don't receive a payment intent that I could cancel. There also doesn't seem to be a way to cancel checkout sessions directly.
I don't know of a way to prevent the scenario you described as the customer in question is explicitly deciding to pay you twice for two different subscriptions.
That said, if your use case requires a customer to have only a single Subscription you could add logic on your end that would do the following:
Set up a webhook endpoint to listen for customer.subscription.created events.
Whenever a new Subscription is created list the Subscriptions belonging to the Customer.
If the Customer has more than one active Subscription cancel the newest one(s) and refund the associated payments. You may also want to send the customer an email letting them know what happened.
I have 1 product in Stripe with 2 prices
1st price is a recurring subscription
2nd price is a one-time payment
I process both by using redirectToCheckout, the first one with mode: subscription and the second one with mode: payment, and both indicating in lineItems the respective price codes
Then, when the payment is fulfilled on Stripe's side, I get webhooks sent to my php backend
With the 1st item I get the event type customer.subscription.created, and the info sent in that webhook includes the price code
I need this price code to be sure that the user has fulfilled the payment for that specific price item
The problem is with the 2nd item, I've been able to identify 4 events that are sent with the webhooks after payment:
customer.created
charge.succeeded
payment_intent.succeeded
checkout.session.completed
And none of them include the price information about what product the user has paid for
Probably I could ask stripe for that information in a fetch operation, but ... it is impossible that there isn't any webhook that includes this basic (?) information
Or maybe I'm understanding it wrongly?
EDIT:
Probably the answer is this one, so that the webhook (checkout.session.completed) by default is not including this information, and it indeed has to be retrieved in a 2nd step
As #ttmarek has said, the answer is here https://stripe.com/docs/expand#includable-properties indicating that one has to retrieve this information if using a single payment
If using a subscription this info is included by default and there's no need to start another request
An alternative to avoid this extra request could be using the amount charged (which comes with most webhooks), provided that you can identify your price from this amount
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.
There is the following event from Stripe that shows a charge has went through:
charge.succeeded
https://stripe.com/docs/api/events/types#event_types-charge.succeeded
From this I can generate an invoice receipt and email it to the customer. Easy enough. However, there is zero information about what is charged in that item -- it only shows the amount. More importantly, it doesn't tell me when the subscription start/end is, which I need to tell the customer in the invoice receipt.
I need to get the different items in the subscription that were charged. It seems like I can use this item instead:
invoice.payment_succeeded
https://stripe.com/docs/api/events/types#event_types-invoice.payment_succeeded
This gives the items in the subscription and also the amount_paid, however it doesn't reference the charge object or anything. I'm also concerned that this event seems a bit more abstracted than the charge.succeeeded/refunded event, so it possibly may not capture anything (please correct me if I'm wrong).
For a subscription, which of the above two methods should I use to trigger when I send an invoice email? Why would one be preferred over the other?
For a subscription, which of the above two methods should I use to trigger when I send an invoice email? Why would one be preferred over the other?
You should prefer the invoice.payment_succeeded event, because as you noticed, it refers directly to the invoice from the subscription and thus has much more of the information that you would need to build a receipt email for the payment.
however it doesn't reference the charge object or anything
The event payload is an Invoice object, which has a charge field with the charge ID for the most recent charge on the invoice(which will be what caused the invoice.payment_succeeded event to trigger). You can retrieve that charge to get further information from that if needed.