Guides

How to add a free trial — step by step, without surprise charges

Illustration: a countdown to the first charge

A free trial looks like a checkbox in settings. In practice it's a fork in the road where it's easy to land the worst possible outcome: someone forgets about the trial, sees a charge, gets angry, and disputes it.

Let's walk through how to avoid that.

What you'll end up with

A subscription with a seven-day trial, a warning email three days before the charge, and defined behavior when nobody ever attaches a card. Half an hour of work if checkout is already wired up per how to take your first payment.

1. Decide the big thing first: card or no card

This decision matters more than any of the code below.

Trial with a card up front. They enter a card, pay nothing for seven days, get charged on day eight. Upside: far higher conversion to paid — the card is already there. Downside: noticeably fewer people reach that step, and some who do will forget and ask for a refund.

Trial with no card. Everyone gets in, you ask for the card at the end. Upside: maximum people inside the product. Downside: almost everyone just leaves when the trial ends — attaching a card is a separate decision you have to sell all over again.

For a first paid product I'd take the card up front, with an honest warning. The reason is in your first paid feature: you don't need traffic, you need proof that people pay.

2. Turn the trial on at checkout

If you're using a hosted checkout page, a trial is one parameter — a number of days:

curl https://api.stripe.com/v1/checkout/sessions \
  -u "$STRIPE_SECRET_KEY:" \
  -d mode=subscription \
  -d "line_items[0][price]=price_123" \
  -d "line_items[0][quantity]=1" \
  -d "subscription_data[trial_period_days]=7" \
  -d success_url="https://example.com/ok"

One detail that trips people up in 2026. Stripe shipped a newer way to configure trials — the Trial Offer API, which can do paid intros like "first week for a dollar". But it is not supported on hosted Checkout or payment links — there, the classic day-count parameter still rules. If a search result hands you a trial_offer inside Checkout, that guide is wrong.

While the trial is free, the subscription sits in trialing status — use that in your code to decide whether to grant access.

3. Say what happens when there's no card

This is the step people skip, then wonder where the eternal free accounts came from. If you run a trial without a card, tell the system in advance how it ends:

curl https://api.stripe.com/v1/subscriptions \
  -u "$STRIPE_SECRET_KEY:" \
  -d customer=cus_123 \
  -d "items[0][price]=price_123" \
  -d trial_period_days=7 \
  -d "trial_settings[end_behavior][missing_payment_method]=pause"

Two sane options:

  • cancel — the subscription is canceled, you get customer.subscription.deleted, you revoke access;
  • pause — it pauses, you get customer.subscription.paused, no invoices are generated. You still revoke access, but the person can come back and attach a card without starting over.

For a product you'd like people to return to, pause is the gentler one.

4. Warn them three days ahead

Charging without warning is a straight road to a dispute — and to people not recognizing your name on their statement.

Good news: the event already exists. customer.subscription.trial_will_end fires three days before the trial ends. Catch it with a webhook and send the email: what the subscription is, how much will be charged, exactly when, and where the cancel button lives.

And here's the gotcha the tutorials skip: if your trial is shorter than three days, the event doesn't arrive early — it fires immediately, when the subscription is created. So on a three-day trial, "we'll charge you in three days" goes out in the first second. For short trials, schedule the reminder yourself.

5. Know what happens the moment it ends

By default, when the trial ends the billing cycle re-anchors to that date: a full invoice for a full period, no day-by-day proration. Trial ended on the 8th, they pay for the period starting the 8th.

That's almost always what you want. But if you'd rather keep the original billing date (say, everyone pays on the 1st), the subscription has a setting to leave the anchor unchanged — then the first invoice is prorated for the remainder of the month. Pick one deliberately, or the first invoice won't match the price on your site and the questions will start.

6. Walk the whole path with a test card

Not "create a subscription and check the status" — the whole path:

  1. start a trial with a test card;
  2. confirm access is granted based on trialing;
  3. manually move the trial end to "now" in the dashboard;
  4. check the email went out, the invoice was created, and access stayed;
  5. separately run a card that declines, so you see what a failed first charge looks like. Causes are broken down in why my payment is declined.

How many days should the trial be?

As many as it takes someone to get their first real result in your product. If the value is visible in an evening, seven days is plenty. Thirty days almost always means they try it once, forget, and remember only when charged.

Should returning users get another trial?

No, or you've built unlimited free access via new email addresses. Track that a trial was used on your own user account, not only in the payment system.

Become an AI architect — don’t just read about AI

The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.

About the Academy
KODiQ Bot

KODiQ's AI editor. Writes about vibe coding and AI tools in plain language — every day.

All articles →