Free Trials

A free trial in your project is one number and one table. The number is prices.trial_days; the table is public.trials, which records that a trial was granted so it is never granted twice.

Everything on this page ships in the base project. It is the same machinery whether the money comes from Stripe or RevenueCat; the two providers differ only in where you type the trial length.

Where the number comes from

public.prices has a trial_days SMALLINT NOT NULL DEFAULT 0 column. Zero means no trial, and zero is the default, so a new project offers no trials until you set one.

Either way, trial_days is what the paywall reads and what the checkout call sends to Stripe as trial_period_days. If it is 0, no badge, no trial button, no trial.

Who gets one

By default, a user gets one trial per price, once. Three separate things enforce that, and they run at different moments.

At checkout: the decision

The checkout session backend only attaches trial settings when all of the following hold:

When a trial is granted the session carries trial_period_days plus trial_settings.end_behavior.missing_payment_method: "cancel", so a trial that ends with no usable card lapses instead of failing payment forever.

After the fact: the record

public.trials is written by manage_trial(), an AFTER INSERT OR UPDATE trigger on public.subscriptions. When a subscription row arrives with status = 'trialing' and both trial_start and trial_end set, it inserts:

INSERT INTO public.trials (user_id, price_id, start_date, end_date)
VALUES (NEW.user_id, NEW.price_id, NEW.trial_start, NEW.trial_end);

The table's primary key is (user_id, price_id), and the function only ever inserts; it never updates or deletes. That is deliberate: the row is the permanent proof that this user has had this trial, so the history survives cancellations, re-subscriptions and plan changes.

It is a backstop, not the gate. If a trialing subscription somehow shows up for a flagged user, manage_trial() records it anyway and raises a WARNING, because the provider has already committed to the trial and the database has to reflect reality. The place to fix a bypass is the checkout check above.

The paywall badge

PriceCard (lib/features/payments/presentation/views/widgets/price_card.dart) shows a Free trial 🎉 badge in the card header, and swaps its CTA from Get started with… to Start N day free trial.

It appears only when trial_days > 0 and none of these three suppressors applies:

Those are the same three conditions the checkout function evaluates server-side, mirrored into the UI so the paywall never advertises a trial that checkout will then refuse. The client copy is a courtesy; the server is the authority.

The rest of the paywall (plan descriptions, feature lists, lifetime prices) is covered on the Paywall page.

Trial-ending notices

Shortly before a trial ends, the buyer gets an email. Nothing about this is provider-specific: the sweep reads public.subscriptions, which both the Stripe webhook and the RevenueCat webhook write to.

SELECT cron.unschedule('trial-ending-notify-sweep');

The lead-day ladder

How much notice a trial earns depends on how long it was:

Two consequences worth knowing:

• The three-hour cadence is what makes the ladder work. The shortest window is 24 hours, so every window still gets several passes, and a failed send is retried within three hours. If you change the ladder, keep the cron interval well under the shortest window.
• The sweep's own lookahead is three days, matching the top rung. Raising a rung above three days without raising that horizon would mean the row is never even fetched.

The email

The template is TrialEndingEmail, in supabase/functions/send-email/_templates/subscriptions/trial-ending-email.tsx. It renders in the recipient's language (from users_prefs.language, English or French), with the subject from supabase/functions/send-email/_templates/l10n.ts: "Your free trial is ending soon".

It has two bodies, chosen from the subscription itself:

"Canceled" means canceled_at is set or cancel_at_period_end is true; both are checked, because a RevenueCat trial that has been canceled keeps status = 'trialing' until it expires, and some cancel reasons leave cancel_at_period_end false.

The CTA points at /billing on your WEBSITE_URL, and delivery uses the same SMTP configuration as the rest of the project's transactional email, so SMTP_HOST and SMTP_FROM must be set for notices to go out.

Allowing more than one trial per user

Since eligibility is nothing more than "is there a row in public.trials", letting someone trial again is a matter of deleting theirs. The table is public.trials; writes are service_role, so this belongs in the SQL editor or a scheduled job, not in client code.

To clear one specific user's trial on one price:

DELETE FROM public.trials
WHERE user_id = '<user_uuid>' AND price_id = '<price_id>';

To reopen trials generally, for example letting anyone who trialed more than a year ago try again:

DELETE FROM public.trials
WHERE end_date < now() - INTERVAL '1 year';

Run that on a schedule and trials become renewable rather than once-ever. pg_cron is already installed, so it can live next to the sweeps:

SELECT cron.schedule(
    'trials-expire-old',
    '0 4 * * *',
    $cron$ DELETE FROM public.trials WHERE end_date < now() - INTERVAL '1 year' $cron$
);