Subscription Lifecycle detail for trial end and payment of first non-zero invoice

[Dean Richardson]

After about a year of having paid subscription plans available for our research providers with 30-day free trials, we just had our first trial-to-paid conversion. :) Yay!

When I discovered this, my excitement quickly gave way to anxiety about all the code I've been putting off writing to handle this possibility. I currently send an email to myself as admin when a trial is 3 days from ending (we receive the relevant webhook), but I don't notify the provider or give them instructions on how to enter their credit card info, though the code for them to do that is accessible on their account settings page.

I found myself wondering "How did the provider know their trial had expired? What prompted them to update their subscription and add a credit card? And how can I track that specific process?"

I could use help understanding the trial-to-paid lifecycle timeline in a little more detail than I've gleaned from the docs thus far. Since we create trial subscriptions without asking for a credit card upfront (and thus we're in "Manual payment" mode), I'm wondering what -- if anything -- Stripe did when the trial expired. Was an email invoice sent to the provider from Stripe? Did Stripe post a "trial expired" webhook? Or perhaps an "invoice failed" webhook?

Clearly I need to send providers my own email to encourage them to convert from trial to paid and add a credit card as their trial comes to an end. But what's the best way for me to actually determine that a trial-to-paid conversion has occurred?

Thanks very much,

Dean Richardson

Genlighten.com

[Remi J.]

Hello,

I'm glad to hear you're starting to see conversions from trials to paid subscriptions, that's a great achievement!

On Stripe's end, we don't send anything to the customer when the trial is about to expire or has expired. We will send you the `customer.subscription.trial_will_end` event, usually three days before the end of the trial. The idea is that your integration would listen for this event and for example email the customer asking them to enter their card details before the end of the trial.

Separately, when the trial ends, the subscription's billing cycle will renew. At that point, a `customer.subscription.updated` event is sent to indicate that the subscription moved from Trialing to Active. An `invoice.created` event is also sent to indicate a new invoice has been created to collect funds from the customer. This invoice is not charged immediately to give you some time to modify it if needed, for example to add extra line items. An hour or two later, we automatically try to pay the invoice. In your case, payment would fail since the customer has no card saved at the time. We would then send the `invoice.payment_failed` event to your endpoint to react accordingly.

After a payment failure for an invoice, we can also send an email to your customer, assuming you have enabled the option in your account settings [1]. This email would contain a link to your website, which you can configure in the same view. This will let customers go to their account settings on your website for example to update their card details.

At that point, your code will collect a card token (tok_XXX) client-side and send it to your server. You will then call the Update Customer API [2] server-side and pass `source: tok_XXXX` to save their new card. This will automatically trigger a new attempt on all past due invoices. If the payment succeeds, you will get an `invoice.payment_succeeded` event to confirm the charge.

I hope this helps!

Remi

[1] https://dashboard.stripe.com/account/recurring

[2] https://stripe.com/docs/api#update_customer

--
You received this message because you are subscribed to the Google Groups "Stripe API Discussion" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-discuss+unsubscribe@lists.stripe.com.
To post to this group, send email to api-d...@lists.stripe.com.
Visit this group at https://groups.google.com/a/lists.stripe.com/group/api-discuss/.