Kangram MCP
Open app
← Blog

Stop Paywalling Your AI Features — Use a Quota Instead

A 402 on the first AI request kills activation. We replaced our hard paywall with a weekly weighted-token quota. Here is the design, the implementation, and what it did to the funnel.

Kangram 5 min read

Stop Paywalling Your AI Features — Use a Quota Instead

Most SaaS hit free users with a 402 the moment they touch the AI feature. Looks clean in code, feels terrible in product. Activation drops, the user never sees the value, you never get the conversion. We replaced our hard paywall with a weekly weighted-token quota. Free users get about 200k DeepSeek-V4-Flash tokens a week. The 402 still fires at the ceiling — but now there is a ceiling, not a wall. Paywalls optimize for conversion. Quotas optimize for habit.

If you ship an AI feature in 2026, you will face this question: how do you let free users try it without going broke? The default answer most teams ship — a hard paywall on first request — is wrong. This is the design we landed on after shipping and unshipping ours, and the implementation details that made it feel honest.

The 402-on-first-request anti-pattern

Here is the pattern we inherited and then ripped out:

// DON'T DO THIS
async function runAssistant(user: User, input: string) {
  if (!user.hasActiveSubscription) {
    throw new ExtError(402, "Subscription required");
  }
  // ... actually run
}

Looks clean. Terrible in product. The user signs up, opens the assistant, types a question, and gets a paywall. They never experience the value. Your activation funnel dies at step one.

The hard-paywall pattern optimizes for the wrong metric (conversion rate of users who already activated) at the cost of the metric that matters (how many users activate at all).

Anatomy of a fair AI quota

A quota that does not feel like a bait-and-switch has four parts:

  1. A window. Weekly is the sweet spot. Daily feels stingy; monthly feels unlimited until you blow through it.
  2. Per-tier limits. Free gets enough to feel the value (~200k tokens/week); paid tiers get enough to never think about it (500k to unlimited).
  3. Weighting by model cost. A token on a cheap model should not consume the same quota as a token on an expensive one. Multiply by a cost weight (DeepSeek-V4-Flash = 0.5x, full models = 1.0x).
  4. A visible usage surface. Users see how much they have left and when the window resets. No surprise 402s.

The weighting is the trick that makes free tiers sustainable. Free users auto-route to cheaper models (which are still genuinely good at task-management NL), their quota buys twice as much real usage, and your cost per free user drops accordingly.

Case study: from hard subscription block to weekly window

What we shipped:

async function assertQuotaAvailable(user: User) {
  const tier = resolveTier(user);
  const limit = tier.quotaWeightedTokensPerWeek; // free: 100k, lite: 500k, pro: Infinity
  const windowStart = subDays(now(), 7);
  const used = await sumWeightedTokensSince(user.id, windowStart);
  if (used >= limit) {
    throw new ExtError(402, "Weekly quota reached", { resetAt: windowStart.plus(7, "days") });
  }
}

A few decisions worth flagging:

  • The same 402 still fires at the ceiling — so the web paywall CTA and the Telegram reply both surface it identically. No new error path.
  • Limits are env-tunable via ASSISTANT_TIER_QUOTA_JSON. Retuning the free tier does not require a redeploy.
  • The /settings/usage page shows current window usage, time-left, and which model answered each turn. No silent downgrades.
  • The free tier auto-routes to DeepSeek-V4-Flash during the 5-hour window, so users get more real tokens per quota unit.

Decision note: we considered a daily quota. Rejected because users do task management in bursts — weekly matches the rhythm of work and feels less surveilled.

Implementation checklist

If you are replacing a paywall with a quota, here is the minimum viable set:

  • One assertQuotaAvailable(user) function on the run path (not per-route — single gate)
  • Weighted token sum over a rolling window
  • Tier-aware limits (env-tunable, not hardcoded)
  • Visible usage page (/settings/usage or equivalent)
  • 402 (or equivalent) at the ceiling, with resetAt metadata
  • Model auto-routing for free tiers (cheaper model = more tokens per quota unit)
  • Surface model choice in the assistant UI (“answered by DeepSeek-V4-Flash”)

What this does to activation

Hard paywall: users hit the wall on first AI request, never form the habit, never convert.

Soft quota: users get one to two weeks of real usage. They build the habit of asking the assistant. When the quota tightens, the upgrade feels like removing friction, not buying access.

We are not going to share conversion numbers here — too early, too sample-size-of-one. But the funnel shape is unambiguous: activation rate (user reaches “first agent action” event) jumped materially the week we shipped the quota. See our AI-agent onboarding funnel post for the instrumentation pattern behind that measurement.

FAQ

Q: Should I put my AI feature behind a paywall? A: Avoid paywalling the first request. Use a weighted-token quota instead — users get a real taste of the value, you keep cost control. A hard 402 on first use kills activation.

Q: How do I limit AI feature costs for free users? A: Use a weighted-token quota: sum tokens consumed over a week, weight by model cost (cheap models = 0.5x), and surface the remainder visibly. Throws 402 only when the ceiling is hit.

Q: What is a weighted token quota? A: A quota where tokens are multiplied by a per-model cost weight before summing. Cheap models consume less quota per token, so users on free tiers get more real usage.

Q: Won’t free users game the system with multiple accounts? A: Some will. The cost of a few abusers is far smaller than the cost of a paywall that kills activation for everyone else. Add abuse limits later if a real pattern emerges.

Q: How often should the quota window reset? A: Weekly is the sweet spot for productivity tools. Daily feels stingy; monthly feels unlimited until you blow through it.

Conclusion

Paywalls optimize for conversion. Quotas optimize for habit. The latter is what compounds. If you are shipping an AI feature in 2026 and your free-tier strategy is “throw a 402 on first request,” rip it out and replace it with a weighted quota. Your activation rate will thank you.

→ Read about our unified assistant architecture · Get started with Kangram · AI-agent onboarding funnel design