How to Implement Trial Expiration in a SaaS App

Trial expiration is the most critical moment in your SaaS conversion funnel. It's the point where a free trial user either becomes a paying customer or churns. Yet most development teams treat it as an afterthought -- a simple date check that returns "trial expired" and hopes for the best.

A well-implemented trial expiration system has two layers: server-side enforcement (protecting your API and data) and client-side experience (guiding users toward conversion). The server layer ensures expired users can't access paid features. The client layer ensures they want to upgrade before they hit that wall.

This guide covers both layers end-to-end with production code examples. We'll build the server-side logic in Node.js, walk through all five client-side UI states, handle the edge cases that trip up most teams, and then show how TrialMoments handles the entire client-side layer so you only need the server portion.

Step 1: Database Schema for Trial Tracking

Your trial data model needs to track when the trial starts, when it ends, the current status, and any grace period. Here is a practical schema that handles the common scenarios:

-- PostgreSQL schema for trial tracking
CREATE TABLE subscriptions (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID NOT NULL REFERENCES users(id),
  plan VARCHAR(50) NOT NULL DEFAULT 'trial',
  trial_start_date TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  trial_end_date TIMESTAMPTZ NOT NULL,
  grace_period_end TIMESTAMPTZ,
  trial_status VARCHAR(20) NOT NULL DEFAULT 'active',
  -- 'active', 'ending_soon', 'expired', 'grace', 'converted'
  upgraded_at TIMESTAMPTZ,
  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- Create index for efficient expiration queries
CREATE INDEX idx_subscriptions_trial_end
  ON subscriptions(trial_end_date)
  WHERE trial_status IN ('active', 'ending_soon');

-- Set trial_end_date on insert (14-day trial)
CREATE OR REPLACE FUNCTION set_trial_end_date()
RETURNS TRIGGER AS $$
BEGIN
  NEW.trial_end_date := NEW.trial_start_date + INTERVAL '14 days';
  NEW.grace_period_end := NEW.trial_end_date + INTERVAL '3 days';
  RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER trigger_set_trial_end
  BEFORE INSERT ON subscriptions
  FOR EACH ROW
  EXECUTE FUNCTION set_trial_end_date();

Step 2: Server-Side Expiration Logic

Your server needs middleware that checks trial status on every authenticated request. Here's a Node.js/Express implementation:

// middleware/trialCheck.js
export function checkTrialStatus(req, res, next) {
  const { subscription } = req.user;

  // Paid users pass through
  if (subscription.plan !== 'trial') {
    return next();
  }

  const now = new Date();
  const trialEnd = new Date(subscription.trial_end_date);
  const graceEnd = new Date(subscription.grace_period_end);

  // Trial is still active
  if (now < trialEnd) {
    const daysRemaining = Math.ceil(
      (trialEnd - now) / (1000 * 60 * 60 * 24)
    );
    res.set('X-Trial-Days-Remaining', daysRemaining);
    res.set('X-Trial-End-Date', subscription.trial_end_date);
    return next();
  }

  // Trial expired but within grace period
  if (now < graceEnd) {
    res.set('X-Trial-Status', 'grace');
    res.set('X-Grace-Period-End', subscription.grace_period_end);

    // Allow read-only access during grace period
    if (req.method === 'GET') {
      return next();
    }

    return res.status(402).json({
      error: 'trial_expired',
      message: 'Your trial has expired. Upgrade to continue.',
      upgradeUrl: '/upgrade',
      graceEnds: subscription.grace_period_end,
    });
  }

  // Trial and grace period both expired
  return res.status(403).json({
    error: 'trial_fully_expired',
    message: 'Your trial and grace period have ended.',
    upgradeUrl: '/upgrade',
  });
}

// Apply to all API routes
app.use('/api', authenticate, checkTrialStatus);

Cron Job for Status Updates and Notifications

// jobs/trialExpiration.js
import { db } from '../db';
import { sendEmail } from '../email';

export async function processTrialExpirations() {
  const now = new Date();

  // Find trials ending in 3 days (send warning)
  const endingSoon = await db.query(`
    UPDATE subscriptions
    SET trial_status = 'ending_soon', updated_at = NOW()
    WHERE trial_status = 'active'
      AND trial_end_date <= NOW() + INTERVAL '3 days'
      AND trial_end_date > NOW()
    RETURNING user_id, trial_end_date
  `);

  for (const sub of endingSoon.rows) {
    await sendEmail(sub.user_id, 'trial-ending-soon', {
      daysLeft: Math.ceil(
        (new Date(sub.trial_end_date) - now) / 86400000
      ),
    });
  }

  // Find newly expired trials
  const expired = await db.query(`
    UPDATE subscriptions
    SET trial_status = 'expired', updated_at = NOW()
    WHERE trial_status IN ('active', 'ending_soon')
      AND trial_end_date <= NOW()
    RETURNING user_id
  `);

  for (const sub of expired.rows) {
    await sendEmail(sub.user_id, 'trial-expired', {
      graceHours: 72,
    });
  }

  // Find expired grace periods
  await db.query(`
    UPDATE subscriptions
    SET trial_status = 'fully_expired', updated_at = NOW()
    WHERE trial_status = 'expired'
      AND grace_period_end <= NOW()
  `);
}

// Run every hour
setInterval(processTrialExpirations, 60 * 60 * 1000);

Step 3: Client-Side UI States

The client side is where most teams underinvest. You need five distinct UI states, each with different messaging, urgency levels, and calls to action:

Client-Side State Machine (JavaScript)

// trialStateMachine.js
// Client-side trial state management

function getTrialState(trialEndDate, gracePeriodEnd) {
  const now = new Date();
  const end = new Date(trialEndDate);
  const grace = new Date(gracePeriodEnd);
  const msRemaining = end - now;
  const daysRemaining = Math.ceil(msRemaining / 86400000);

  if (msRemaining > 3 * 86400000) {
    return {
      state: 'active',
      daysRemaining,
      urgency: 'low',
      message: `${daysRemaining} days left in your trial`,
    };
  }

  if (msRemaining > 86400000) {
    return {
      state: 'ending_soon',
      daysRemaining,
      urgency: 'medium',
      message: `Only ${daysRemaining} days left in your trial`,
    };
  }

  if (msRemaining > 0) {
    const hoursLeft = Math.ceil(msRemaining / 3600000);
    return {
      state: 'last_day',
      hoursRemaining: hoursLeft,
      urgency: 'high',
      message: `Trial ends in ${hoursLeft} hours`,
    };
  }

  if (now < grace) {
    const graceHours = Math.ceil((grace - now) / 3600000);
    return {
      state: 'grace_period',
      graceHoursRemaining: graceHours,
      urgency: 'critical',
      message: `Trial expired. ${graceHours}h to upgrade.`,
    };
  }

  return {
    state: 'fully_expired',
    urgency: 'blocked',
    message: 'Your trial has ended.',
  };
}

// Render appropriate UI based on state
function renderTrialUI(trialEndDate, gracePeriodEnd) {
  const trial = getTrialState(trialEndDate, gracePeriodEnd);

  switch (trial.state) {
    case 'active':
      showSubtleBanner(trial.message);
      break;
    case 'ending_soon':
      showWarningBanner(trial.message);
      break;
    case 'last_day':
      showCountdownTimer(trial.hoursRemaining);
      break;
    case 'grace_period':
      showGraceOverlay(trial.graceHoursRemaining);
      break;
    case 'fully_expired':
      showExpiredOverlay();
      break;
  }
}

// Each of these render functions is 50-100 lines of code
// covering: DOM creation, styling, responsive layout,
// dark mode, animations, dismissal logic, localStorage...
// Total for all 5 states: ~500 lines minimum

Step 4: Handling Edge Cases

Edge cases are where most trial expiration implementations break down. Here are the ones that catch teams off guard:

// Solution: always expire at end-of-day in user's timezone
function getTrialEndDate(startDate, durationDays, userTimezone) {
  const start = new Date(startDate);
  const end = new Date(start);
  end.setDate(end.getDate() + durationDays);

  // Convert to user's timezone end-of-day
  const formatter = new Intl.DateTimeFormat('en-US', {
    timeZone: userTimezone,
    year: 'numeric', month: '2-digit', day: '2-digit',
  });

  const userDate = formatter.format(end);
  // Set to 23:59:59 in user's timezone
  return new Date(`${userDate} 23:59:59 ${userTimezone}`);
}

// Pass trial state via API headers (see middleware above)
// Client reads from headers, not local clock
async function fetchTrialState() {
  const res = await fetch('/api/me');
  const daysLeft = res.headers.get('X-Trial-Days-Remaining');
  const endDate = res.headers.get('X-Trial-End-Date');
  const status = res.headers.get('X-Trial-Status');
  return { daysLeft: parseInt(daysLeft), endDate, status };
}

Step 5: Notification Triggers

Notifications drive conversions by reaching users at critical decision points. Here's the notification schedule that maximizes trial-to-paid conversion:

The Done-for-You Shortcut: TrialMoments Handles the Client Side

Everything we've covered for client-side UI -- the five states, the countdown timer, the warning banners, the expired overlay, the responsive design, the dark mode support -- that's roughly 60-80 hours of development time. TrialMoments replaces all of it with a 5-minute integration.

Your team still implements the server-side logic (database schema, API enforcement, cron jobs). That's the part that must be custom to your stack. But the entire client-side experience is done for you:

<!-- Replace 500+ lines of custom client-side code with: -->
<script src="https://cdn.trialmoments.com/sdk.js"></script>
<script>
  // Fetch trial end date from your API
  fetch('/api/subscription')
    .then(res => res.json())
    .then(({ trialEndDate, plan }) => {
      if (plan === 'trial') {
        TrialMoments.init({
          accountId: 'your-account-id',
          trialEndDate: trialEndDate,
          upgradeUrl: 'https://yourapp.com/upgrade'
        });
      }
    });
</script>

<!-- TrialMoments automatically handles:
  ✓ Welcome message on first visit
  ✓ Countdown timer with days/hours remaining
  ✓ Expiration warning at 3 days / 1 day
  ✓ Trial-ended overlay with upgrade CTA
  ✓ Blocked feature prompts
  ✓ Dark mode detection
  ✓ Responsive design for all screen sizes
  ✓ Timezone-safe countdown calculations
  ✓ Dismissal persistence via localStorage
  ✓ Analytics on every interaction -->

Frequently Asked Questions