How to add a paywall and usage limits to a Next.js and Supabase app

A free plan only makes money if people hit a limit and want to go past it. That needs three things: a record of who is on which plan, a count of what they used, and a check on the server that the browser can’t skip.

1. Store the plan and the usage

create table public.usage (
  user_id    uuid not null references auth.users(id) on delete cascade,
  period     date not null default date_trunc('month', now()),
  used       integer not null default 0,
  primary key (user_id, period)
);
alter table public.usage enable row level security;
create policy "read own usage" on public.usage for select using (auth.uid() = user_id);

Keep the plan on the user’s profile, set only by your Stripe webhook. Users can read their own usage (for the meter in your UI) but never write it.

2. Check and count on the server, in one step

Do the check and the increment together in the database, so two requests at the same moment can’t both slip under the limit. A small SQL function called with the service role works well: it raises an error when the user is over their plan’s limit, and adds one otherwise.

// In your route handler, before doing the paid work:
// use_credit is your SQL function: it raises 'limit_reached' or adds one to this month's usage.
const { error } = await admin.rpc('use_credit', { p_user_id: user.id })
if (error?.message.includes('limit_reached')) {
  return NextResponse.json({ error: 'Limit reached', details: { reason: 'limit_reached' } }, { status: 402 })
}

3. Show the upgrade prompt at the wall

When the server answers with your limit code, open a paywall right where the user was working: what they tried to do, what the next plan unlocks, and one button. Also show a usage meter before they get there ("8 of 10 used this month"), so the wall is never a surprise.

4. Nudge before the limit

At around 80% of the limit, a small upgrade nudge converts better than a hard stop alone, because the user isn’t blocked yet and doesn’t feel cornered.

The shortcut

Venturi Pro includes the UI for every step: a paywall modal, feature gate drawer, usage meter and upgrade nudge. Add them with npx venturi-dev add paywall-modal usage-meter upgrade-nudge, and the Venturi Pro starter (npx venturi-dev init) includes the plans, credits and Stripe billing behind them.