Identifying Trials from Stripe Invoices

January 17th, 2019

I recently calculated trial conversion in Stripe, but found it remarkably hard to find historical trials. In case others have need, here’s what I found.

Invoices

Invoices are the one historical record of Stripe that you have access to (events have it in the customer.subscription.updated, but access to events is limited to the last 30 days). As such I looked here first.

They don’t have a trial attribute (as I initially thought), nor is the plan_id available. Nor can you rely on filters for amount_due = 0, due to discounts and free plans. Instead, you must look at invoice line items.

For invoice line items, if…

• amount is zero
• plan is a paid plan
• quantity isn’t zero

then, the line item’s period_start and period_end are the trial period. It’s important to look at the line item’s period, not the overall invoice’s, as the invoice period_start and period_end can often be simultaneous.

To confirm, I emailed Stripe support. Their response is below:

First, we would have to find out which plan IDs (plan_**) represent plans created with trials attached.

Then, we would have to run a list.all.invoices[0], specifying a large number for maximum as to return all invoices, and filter for the plan_ID associated with the trial subscriptions. This would then provide a list of all invoices generated under the trial subscriptions.

Next, we would have to separate out the customer ID’s, to find which invoices belonged to which customer.

The final step would be to take the UNIX timestamp of the period_start of the first invoice, and the period_end for the last 0 value invoice for each customer, and enter this into an Epoch converter[1], in order to find the range of time they were on a trial for.

They miss the final point (that the invoice start and end period can be incorrect), but the rest of it confirms my approach.