Free API to Paid Tier — Rate Limiting, Stripe Metered Billing, and the Freemium Gate.

One decision before you write a single line of billing code.

Before you pick Stripe or Lago, before you configure a rate limiter, you must answer one question: what does "free" mean for your API, and what specifically forces a user to stop being free?

The gate is not your pricing page. It is the moment of friction: a 429 rate limit response, a soft "you've hit your monthly quota" wall, a disabled endpoint. Without a defined gate, you have built a subsidy program, not a product. For a solo founder shipping a FastAPI/Vercel API, the sequence is:

1. Pick a gate that is real but not punishing.
2. Instrument the gate with a stateful counter — which requires external Redis on serverless.
3. Decide whether overages block or alert — only then does billing infrastructure matter.

The three decisions — what to gate, how to count it, and how to charge beyond it — are the entire implementation problem.

The three monetization models, ranked for an API builder.

Usage-based pricing is not an emerging trend. According to OpenView Partners' State of Usage-Based Pricing, three out of five SaaS companies now use some form of UBP. For API and infrastructure companies specifically, the adoption rate is higher still. The tradeoffs that matter for a solo builder are below — not as a pricing textbook, but as a comparison ranked by what you can actually ship this week.

Per-Call (Pay-as-You-Go)

Each API call or unit of output is billed individually. Real examples with current published pricing:

• Twilio SMS: $0.0083 per outbound SMS (US long code); pure pay-as-you-go, no monthly minimum (twilio.com/en-us/sms/pricing/us).
• OpenAI API: GPT-5.4 mini at $0.75 per 1M input tokens; no standing free tier and no credit grant for new accounts as of late 2025 (openai.com/api/pricing).

AgentMall fit: Per-call is ideal when API calls have direct measurable value. Risk: customers cannot predict bills, which creates upgrade hesitation. At low traffic (under 10K req/day), per-call revenue is negligible — the model is primarily a signal mechanism at this stage.

Per-Seat

Price tied to the number of users or API keys, not consumption. Weak fit for an AgentMall API — agent traffic is programmatic, not tied to human seats. Per-seat billing creates friction without a natural correlation to value delivered.

Flat-Tier (Subscription with Included Volume)

Fixed monthly price grants access to a defined call volume. Overages either block (hard gate) or accrue extra charges (soft gate). Real examples:

• Cloudflare Workers: Free plan 100K requests/day; Standard $5/month includes 10M requests/month, then $0.30/million additional (developers.cloudflare.com/workers/platform/pricing).
• Zuplo API Gateway: Free tier 100K requests/month; Builder $25/month up to 1M requests/month (zuplo.com/pricing).
• Unkey API Key Management: 150,000 verifications/month free (unkey.com).

Model Comparison

Designing a free tier that converts, not subsidizes.

Free-to-Paid Conversion Benchmarks

From Lenny's Newsletter — the most widely cited source for freemium conversion benchmarks:

• Freemium self-serve: 3%–5% is "good," 6%–8% is "great."
• Developer-focused products specifically: median conversion rate is 5% — half that of non-developer products. "It's a truism that developers are a tough crowd to sell to — and the data supports that intuition."
• a16z rule of thumb: "Below 5% in a year (cohorted) is our usual rule of thumb for a suboptimal free plan in SaaS businesses."

Practical interpretation: If you have 1,000 free-tier API users at 6 months, expect 15–50 conversions under normal conditions. Zero conversions after 200+ active free users means your gate is either too generous or your paid value proposition is unclear.

What to Gate

The gate must create real friction without preventing the "aha" moment. Gate options ranked by conversion pressure:

1. Feature gating — some endpoints only on paid (low friction; easy to circumvent).
2. Volume gating — N calls/month, then block (most common; creates natural upgrade pressure).
3. Rate gating — N calls/minute throttled, not blocked (less effective; users simply slow down).
4. Data gating — truncated results on free tier (effective for data APIs).
5. Recency gating — real-time data on paid, delayed on free (highly effective for time-sensitive APIs).

For an AgentMall commerce API, recommend volume + feature gating combined. Free tier gets product lookup endpoints with 1,000 calls/month; paid tier unlocks inventory sync, webhook events, and bulk endpoints.

Free Tier Benchmarks

The "Free Forever" Trap

The Heroku post-mortem is canonical. From dev.to's analysis: "For a decade, Heroku offered a generous free tier... this filled Heroku's infrastructure with abandoned crypto miners, dormant Slack bots, and student projects that hadn't been touched in five years... In 2022, Heroku killed the free tier. The backlash was immense, but the business logic was sound."

Real founder story from Reddit r/SaaS (2025): "Our free users make around 8 million API calls monthly, compared to just 6 million from our paying customers. This means free users account for 57% of our overall traffic but contribute nothing to our revenue... just 12 free users were responsible for 4 million of those calls." Resolution: capped free tier at 1,000 calls/day.

Rate limiting on FastAPI + Vercel — the only stack that actually works.

The Vercel Serverless Constraint

Vercel serverless functions are stateless. Each invocation spins up a new Lambda context with no shared memory. In-memory rate limiting (a Python dict counting requests) resets on every cold start and cannot coordinate across concurrent invocations.

From Reddit r/nextjs: "Sticking something in front of Vercel is the only option to truly rate limit. Any rate-limiting done via NextJs code paths still counts as an invocation, end of story." / "Upstash Rate Limit... is a pretty good framework-aware solution, also they are providing rate limit analytics for you so you can easily find abuses/abusers."

Solution: External stateful store. The go-to for Vercel is Upstash Redis — an HTTP-based (REST) Redis interface that works without persistent TCP connections. That requirement is exactly what serverless needs.

The Four Rate Limiting Algorithms

Token Bucket

Each user has a bucket with capacity N tokens. Each request spends one token. Tokens refill at a fixed rate. Allows bursts up to bucket capacity, then enforces steady-state rate. Best for: public APIs with legitimate bursty traffic. Per arcjet's algorithm comparison: "Token bucket is the strongest general-purpose default for APIs."

Fixed Window

Counter increments per request, resets at the window boundary (e.g., top of each minute). A user can make 2× their limit by hitting the boundary (N calls at 11:59:59 + N calls at 12:00:00). Best for: simple implementations, low-stakes limits. Weakness: boundary exploitation.

Sliding Window

The window rolls with the current timestamp — counts requests in the past N seconds from now. Smooths the fixed-window boundary problem. Best for: APIs where fair distribution matters. Upstash's SlidingWindow algorithm is available natively.

Leaky Bucket

Requests fill a queue; they drain at a constant rate. No bursts. Best for: shaping outbound traffic to a downstream service. Not ideal for: inbound API rate limiting where you want to allow bursts.

For FastAPI/Vercel: Token bucket or sliding window via Upstash.

slowapi — FastAPI Rate Limiting Library

Source: github.com/laurentS/slowapi — 1,700+ stars, 7,500+ dependent projects.

• Install: pip install slowapi
• Backends: Redis, memcached, in-memory fallback
• Key constraint: the request argument must be explicitly passed to the endpoint function
• Vercel compatibility: configure Upstash Redis as the backend using the redis:// URL

from slowapi import Limiter, _rate_limit_exceeded_handler
from slowapi.util import get_remote_address
from slowapi.errors import RateLimitExceeded
from fastapi import FastAPI, Request

limiter = Limiter(key_func=get_remote_address)
app = FastAPI()
app.state.limiter = limiter
app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)

@app.get("/api/products")
@limiter.limit("100/day")  # free-tier cap per IP
async def get_products(request: Request):
    # Note: 'request' argument is mandatory for slowapi to hook
    return {"products": []}

For per-API-key rate limiting (recommended over per-IP for authenticated APIs):

def get_api_key(request: Request):
    return request.headers.get("X-API-Key", get_remote_address(request))

limiter = Limiter(key_func=get_api_key)

Upstash Redis SDK — The Recommended Serverless Solution

At under 10K req/day: fits within Upstash's free tier exactly. 10K additional commands costs $0.02.

# Install: pip install upstash-ratelimit upstash-redis
from fastapi import FastAPI, HTTPException, Request
from upstash_ratelimit import Ratelimit, FixedWindow, SlidingWindow
from upstash_redis import Redis

app = FastAPI()
redis = Redis.from_env()  # reads UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN

# Fixed window: 100 requests per day per API key
ratelimit = Ratelimit(
    redis=redis,
    limiter=FixedWindow(max_requests=100, window=86400),  # 86400 seconds = 1 day
    prefix="free_tier"
)

@app.get("/api/products")
async def get_products(request: Request):
    api_key = request.headers.get("X-API-Key", request.client.host)
    response = ratelimit.limit(api_key)

    if not response.allowed:
        raise HTTPException(
            status_code=429,
            detail="Free tier limit exceeded. Upgrade at https://yourapi.com/pricing",
            headers={"X-RateLimit-Limit": str(response.limit),
                     "X-RateLimit-Remaining": "0",
                     "Retry-After": "86400"}
        )
    return {"products": [], "remaining": response.remaining}

Source: upstash.com/docs/redis/tutorials/python_rate_limiting.

Vercel environment setup: Add UPSTASH_REDIS_REST_URL and UPSTASH_REDIS_REST_TOKEN to Vercel environment variables. Redis.from_env() reads both automatically.

Stripe Meters — the only usage path for new builds.

Meters vs. Usage Records — The Critical Distinction

In April 2024, Stripe launched the Meters API as a new, recommended path for usage event ingestion. This is distinct from the older "usage records" approach. For any new integration in 2025–2026, use Meters.

From Stripe's Sessions 2024 announcement: "We launched support for usage-based billing with our new Meters API, so you can now ingest, aggregate, and view usage events on Stripe in real time."

From Prefab.cloud's analysis: "The great thing about Stripe's new support for Usage Based Billing and Meters is that the 'usage' part has gotten very simple and is hardly something you need to think about anymore."

The Stripe Meters API Flow (Four Steps)

Step 1 — Create a Meter (one-time setup)

# From Stripe API Reference: https://docs.stripe.com/api/billing/meter/create
curl https://api.stripe.com/v1/billing/meters \
  -u "sk_live_YOUR_KEY:" \
  -d "display_name=API Calls" \
  -d "event_name=api_call" \
  -d "default_aggregation[formula]=sum" \
  -d "value_settings[event_payload_key]=value" \
  -d "customer_mapping[type]=by_id" \
  -d "customer_mapping[event_payload_key]=stripe_customer_id"

Step 2 — Create a Product and Meter-linked Price via Stripe Dashboard

Create a recurring product, set pricing model to "Usage-based," set pricing structure to "Per unit," link the price to your meter by name.

Step 3 — Report Usage Events on every qualifying API call

import stripe
import time

stripe.api_key = "sk_live_YOUR_KEY"

def report_api_call(stripe_customer_id: str, call_count: int = 1):
    """Call this after each successful paid API request."""
    stripe.billing.MeterEvent.create(
        event_name="api_call",
        payload={
            "value": str(call_count),
            "stripe_customer_id": stripe_customer_id,
        },
        identifier=f"call_{stripe_customer_id}_{int(time.time())}",
        # identifier makes the event idempotent
    )

FastAPI middleware pattern for automatic metering:

from fastapi import FastAPI, Request
import stripe, time

app = FastAPI()
stripe.api_key = "sk_live_YOUR_KEY"

@app.middleware("http")
async def meter_paid_requests(request: Request, call_next):
    response = await call_next(request)

    # Only meter successful paid-tier requests
    if response.status_code == 200 and request.state.is_paid_tier:
        stripe_customer_id = request.state.stripe_customer_id
        if stripe_customer_id:
            # Fire-and-forget: don't block response waiting for Stripe
            stripe.billing.MeterEvent.create(
                event_name="api_call",
                payload={"value": "1", "stripe_customer_id": stripe_customer_id}
            )
    return response

Step 4 — Invoice Flow

Stripe bills customers at the end of their subscription period based on aggregated meter data. The upcoming_invoice endpoint reflects metered usage (with up to 30-second lag in test mode).

Stripe Billing Fees

From Stripe's pricing page:

What this means in practice:

• At $1,000 MRR: Stripe Billing costs $7/month; card processing ~$30–$45/month; total Stripe cut ~$37–$52 (3.7%–5.2%).
• The 0.7% fee becomes meaningful at ~$88,500 MRR, where it equals the $620/month annual contract floor.
• For a solo founder at < $5K MRR: use pay-as-you-go. Do not sign an annual contract.

Alternatives — Lago and Others

• Lago: Open-source billing platform. Self-hosted: free (Docker/Kubernetes). Cloud: Business and Enterprise tiers, pricing not publicly listed (contact sales). Best for founders who have hit Stripe's 0.7% pain point at scale, or need complex metering (dimensional pricing, prepaid credits). Not for early-stage — the ops burden is disproportionate when Stripe's 0.7% on $2K MRR is $14/month.
• Paddle: Merchant-of-record model; handles tax and global compliance. 5% + $0.50 per transaction [UNVERIFIED — verify at paddle.com/pricing]. Best for international sales with VAT/GST complexity.
• Orb: Usage-based billing infrastructure for complex models. Pricing not publicly listed [UNVERIFIED — verify at withorb.com/pricing]. Best for multiple meters and dimensional pricing.

How much of the stack do you want to own?

The core question is how much of the infrastructure stack you want to own vs. outsource. Five options, one comparison table.

Option A — DIY FastAPI + Upstash Redis

What you build: API key table in your DB, FastAPI middleware (validate key → check Redis counter → increment Redis counter), Stripe Billing subscription for paid customers, Stripe Meters for usage reporting.

• Monthly cost at low volume: $0 (Upstash free tier under 10K req/day) + 0.7% Stripe on billing volume
• Pros: full control, no vendor lock-in, zero additional tooling cost at low volume
• Cons: you build API key management logic, you build Stripe ↔ DB sync (webhook handler), no built-in developer portal, 2–4 weeks minimum implementation time for a correct abuse-resistant system
• Verdict: Best for founders who want to understand the stack deeply and minimize per-seat tooling costs.

Option B — Unkey

Open-source API key management platform (unkey.com). Handles: key creation, management, validation, per-key rate limiting, usage analytics, IP allowlisting, audit logs, globally distributed low-latency key verification.

• Free tier: 150,000 verifications/month, no credit card required
• One API call in your FastAPI dependency replaces your entire key management layer

import unkey
from fastapi import FastAPI, Header, HTTPException

client = unkey.Client(api_id="YOUR_API_ID")
app = FastAPI()

async def validate_api_key(x_api_key: str = Header(...)):
    result = await client.keys.verify(key=x_api_key)
    if not result.valid:
        raise HTTPException(status_code=401, detail="Invalid API key")
    if result.code == "RATE_LIMITED":
        raise HTTPException(status_code=429, detail="Rate limit exceeded")
    if result.code == "USAGE_EXCEEDED":
        raise HTTPException(status_code=402, detail="Upgrade required")
    return result

Verdict: Best for founders who want to eliminate API key management entirely. Pairs with Stripe Billing for payment. Adds vendor dependency but removes a non-trivial implementation surface.

Option C — Zuplo

Fully managed API gateway (zuplo.com). Handles: rate limiting, API key issuance, usage metering, Stripe billing integration, developer portal — as an integrated platform.

• Free: $0/month — 100K requests/month, unlimited API keys
• Builder: $25/month — up to 1M requests/month, 1,000 consumers, 2 custom domains
• Vercel integration: Zuplo sits in front of your FastAPI as a proxy; your app handles business logic; Zuplo handles auth, rate limiting, metering, billing before the request reaches your code

From Zuplo's comparison: "Stripe Billing does not enforce quotas... Zuplo enforces quotas at the edge."

Verdict: Best for founders who want a complete billing-integrated gateway with a customer-facing portal. Main risk: $25/month is a real carry cost at zero revenue, and the gateway pattern puts Zuplo in your critical path.

Option D — Stripe Billing Native (No Gateway)

Stripe alone, without an API gateway, does NOT provide: API key issuance or validation, rate limiting or quota enforcement, real-time request counting, or a developer portal. Stripe must be paired with at least Upstash Redis + your own key management layer.

Option E — Lago (Self-Hosted)

Best for founders who have hit Stripe's 0.7% pain point at scale or need complex metering. Not for early-stage — disproportionate ops burden.

Stack Comparison

Six mistakes that kill conversion or invite abuse.

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1735689600
Retry-After: 86400
Content-Type: application/json

{"error": "rate_limit_exceeded", "message": "Free tier limit: 100 calls/day. Upgrade at https://yourapi.com/pricing"}

Eight questions an API operator actually asks.

import hashlib, secrets

def generate_api_key() -> tuple[str, str]:
    """Returns (plaintext_key_for_user, hashed_key_for_db)"""
    plaintext = "sk_" + secrets.token_urlsafe(32)
    hashed = hashlib.sha256(plaintext.encode()).hexdigest()
    return plaintext, hashed

async def validate_key(x_api_key: str = Header(...), db=Depends(get_db)):
    key_hash = hashlib.sha256(x_api_key.encode()).hexdigest()
    record = await db.get_api_key(key_hash)
    if not record or record.revoked:
        raise HTTPException(status_code=401)
    return record

The spec is written. The tools exist. The pricing is known.

Upstash Redis is free under 10K requests/day. Stripe Billing costs $0 until you have revenue. Unkey's free tier covers 150,000 key verifications per month. For a solo founder with a working FastAPI/Vercel API, the path from "no billing" to "free tier with paid upgrade" is a 6–12 hour project using the stack above. The earlier you instrument your gate, the more usage data you have when your first paying customer appears — and the more confidently you can price.

The rest of the AgentMall build is one spoke away. Read the AgentMall 30-Day Roadmap.