First off, I love Stripe. I have found their APIs and dashboard to be well-thought-out and well tested in general, and definitely way better in just about every way from other payment processors I have had the misfortune to use for clients.
But then I had to create free trials for a client, and I had to ask myself, what were they thinking?
While testing, I added trials to the subscription plans and…customers got charged right away. Um, that’s not how trials work!
Worst of all, the usually excellent and exhaustive Stripe API Docs were not helpful. The internet was, likewise, lacking in details are to how to get the trials to actually be applied without them being specifically added at the time of purchase by API. In my particular case, I was working with a client who was tech-savvy enough to use the Stripe Dashboard. He wanted to be allowed to create and adjust Subscription Plans as needed for marketing purposes without requiring code or database changes.
I did eventually figure it out, and so I decided to write this up to save others some time. Here you go:
Step 1: Create a Product
You may think of them as Subscription Plans, but in the Stripe Dashboard, they are called Product, and then within a Product you can have multiple Prices. When adding your Product, be sure to use the labeling fields Stripe gives you to clearly define each Price or you may get confused later.
There is an expandable field for “Add a Free Trial” to click to add it. In my case, both Prices would need to have a 30-day trial.
You can create a trial for a number of Days only, but it can be up to 731 days, so…cool?
Step 2: Add All Prices
Add all of your Prices (i.e. Subscription Plans). If you screw up, or forget to label or add your trial, you need to click on the ellipses or the whole line to make your changes. From what I’ve read, changes made to a Price will only affect NEW subscribers, so you can change your trial to be shorter and it will not affect the current subscribers who were marketed a longer trial.
Step 3: Create Your Purchase System in the API
If you test this now, you will notice that your trial does not work out-of-the-box when you process a subscription purchase. I’m sure they have a reason to leave the trial there as some kind of “optional” idea for developers to engage, or maybe it’s weird due to some long-ago coding decision, but…annoying.
Step 4: Engage Your Inner Trial
This is how one system I built using the Stripe SDK charges customers–your code may be different, but should be somewhat similar.
First, you create a customer with a payment method and set it as the default payment method.
$customer = \Stripe\Customer::create([ 'payment_method' => $_POST['payment_method'], 'email' => $_POST['email'], 'invoice_settings' => [ 'default_payment_method' => $_POST['payment_method'] ] ]);
Then, you create a new subscription for that customer that you just created, using it’s new Stripe id:
$subscription = \Stripe\Subscription::create( [ 'customer' => $customer->id, 'items' => [['plan' => $stripe_plan['stripe_id']]], 'trial_from_plan' => true, 'expand' => ['latest_invoice.payment_intent'] ]);
Did you catch that sneaky line of code in there?
'trial_from_plan' => true,
Yep, that’s all you need to tell your subscription that it should go ahead and apply that trial you setup.
When starting out working with Stripe, be sure to also watch out for these two things:
- Use Try/Catch and allow for every error. There are several “generic” errors that, if not caught, will send your application into a customer-error-facing tizzy. This StackOverflow item has great sample code to help you out: Catching Stripe errors with Try/Catch PHP method.
- Do not let users determine what you send to Stripe for Coupons. Stripe calls will fail if a coupon sent via API is wrong. I recommend building your own Coupon creator on your site that both creates coupons in stripe via API and establishes a database to check coupons against at checkout. If you don’t have it in your database, let the user know and only send verified coupons over.