Free-tier limits and how to scale

Internal reference. Numbers as of November 2025; check each provider's pricing page for the current value before making a buying decision.

A "we hit this" event is good news -- it means real users are using Shelfie. Each row below tells you what to do when that happens.

At-a-glance

Service	Free-tier cap	What "we hit it" looks like	Pricing tier above free
Vercel	100 GB-hours functions, 100 GB bandwidth, 1 concurrent build	Build queue or 429 from Vercel	Pro at $20/user/mo
Supabase	500 MB database, 1 GB file storage, 50,000 MAUs, 2 GB bandwidth	Storage warning email, slower queries	Pro at $25/mo + usage
Resend	3,000 emails/month, 100/day	"rate_limit_exceeded" on send	Pro at $20/mo (50k emails), Scale at $90/mo (100k)
Anthropic Claude API	none (pay-as-you-go from day one)	nothing -- you're billed per token	already paid; tier-up is automatic above ~$5k/mo
Google Gemini API	1,500 free image-gen requests/day on Gemini 2.5 Flash Image (Tier 1)	"rate_limit" or "quota_exceeded"	Tier 2 = pay-as-you-go ($0.039/image for 2.5 Flash Image)
Google Books API	1,000 requests/day per project	403 from Google Books	up to 100,000 free with billing enabled
OpenLibrary	"be reasonable" -- soft 100 req/min from one IP	429s	bring your own mirror or self-host (rare)
Cloudflare R2 (planned)	10 GB storage free, 1M Class A ops/month, 10M Class B ops/month, no egress fee	warning email	$0.015/GB/month after 10 GB
Voyage AI (planned)	50M tokens free total	429 once exhausted	$0.06/M tokens after free 50M
Stripe	no free monthly cap; standard fees from $0	n/a (per-transaction fees: 2.9% + 30¢)	volume discount via support; Stripe Atlas/Payments-as-a-service for scale
GitHub	unlimited private repos for individual; 2,000 Actions minutes free	n/a unless we add CI heavy	Team at $4/user/mo
Name.com (registrar)	n/a (annual fee on the domain)	renewal notice	move to Cloudflare Registrar at-cost; ~$10/yr saved

Per-service detail

Vercel

Free tier: 100 GB bandwidth/month, 100 GB-hours of serverless function compute, 6,000 build minutes, 1 concurrent build. Edge runtime: 1M invocations/month.
Hit it when: roughly 100k-200k page views/month across the marketing landing + library pages, depending on cache hit rate.
Scale: Vercel Pro, $20/user/month. Adds 1 TB bandwidth, 1,000 GB-hours functions, 6,000 build minutes, faster builds, password-protected previews. Includes one team seat.
Action: Vercel dashboard → Settings → Plan → Upgrade to Pro.
Optimization before paying: turn on revalidate on /u/[username] (already at 60s). Add revalidate to the marketing / page. Move app/photos/[id]/route.ts to R2 so photos don't bill against function compute.

Supabase

Free tier: 500 MB database, 1 GB file storage, 50,000 monthly active users, 2 GB bandwidth, no automated backups, projects pause after 7 days of inactivity.
Hit it when: ~10,000 books per user × 1,000 users approaches the 500 MB limit. Or any active project (you'll never hit the 7-day pause once we have real users).
Scale: Supabase Pro, $25/month + usage. Includes 8 GB database, 100 GB file storage, daily backups (7 day retention), no project pausing, and unlocks add-ons.
Action: Supabase dashboard → Settings → Billing → Upgrade. Critical: enable PITR (Point-in-Time Recovery) as soon as you upgrade -- otherwise we're one bad migration from data loss.
Optimization before paying: nothing -- the moment we go public, upgrade to Pro for backups alone. Free tier without backups is fine for the dev project; the production project must be Pro before launch. RUNBOOK.md flags this.

Resend

Free tier: 3,000 emails/month, 100/day, 1 verified domain.
Hit it when: ~100 active daily users (each magic-link sign-in is one email; we also send notification emails for lent-out reminders later).
Scale: Pro at $20/month for 50,000 emails. Scale at $90/month for 100,000.
Action: Resend dashboard → Plans → upgrade. The API key keeps working, no code change.

Anthropic API

Tier system: Tier 1 starts at $5 deposit. As spend grows, Anthropic auto-promotes you to Tier 2 ($40 spend in 7+ days), Tier 3 ($200), Tier 4 ($400). Higher tiers = higher rate limits and concurrency.
Hit it when: hard limits at Tier 1 are 50 RPM and 50K input TPM for Sonnet. We won't hit those for a while because each shelfie is one call, ~2K tokens, and prompt caching reduces the recurring system prompt to nothing after the first 5 minutes.
Costs: Sonnet 4.6 is $3/M input + $15/M output. A typical shelfie call is 2,000 input + 600 output = $0.015. Cache hits cut recurring system-prompt input cost by 90%. Photograph 1,500 books -> ~$0.50 in API spend. Cheap.
Scale: spend more, get auto-promoted. To go faster: email compliance@anthropic.com (yes, that's the right alias) for tier elevation.

Google Gemini

Free tier: Tier 1 (just an API key, no billing on file): 1,500 requests/day for Gemini 2.5 Flash Image, lower limits for higher-quality models.
Hit it when: only triggered by npm run gen-graphics, which runs once per design refresh. We won't hit it under normal app use.
Scale: enable billing on the Google Cloud project (any credit card). That moves you to Tier 2: $0.039/image for 2.5 Flash Image, no daily cap. Imagen 4 is $0.04/image; Imagen 4 Ultra is $0.06.
Action: https://console.cloud.google.com/ → select project → Billing → link a card.

Google Books API

Free tier: 1,000 requests/day per project, no API key needed.
Hit it when: a heavy import + many cover misses for niche books. ~1,000 books imported/day with ~100% miss rate = right at the cap.
Scale: same Google Cloud Console → enable billing on the project, set the API to allow up to 100,000/day free. Past that, contact Google Books partner support.

OpenLibrary

Free tier: no formal limit but their docs ask for under 100 requests/min from a single IP.
Hit it when: a bulk re-enrichment script. We're way below today (50/73 books are enriched on first try).
Scale: respect their User-Agent header (we already send shelfie/0.1); add 250-ms throttling between requests if we ever bulk-process. They'll email if abuse is detected.

Cloudflare R2 (planned, photo storage)

Free tier: 10 GB storage, 1M Class A operations/month, 10M Class B operations/month, no egress fees ever.
Hit it when: 10 GB ≈ 5,000 shelfie photos at ~2 MB each.
Scale: $0.015/GB/month after 10 GB; Class A ops $4.50/M, Class B $0.36/M.
Action: Cloudflare dashboard → R2 → Subscribe to Workers Paid ($5/month minimum).

Voyage AI (planned, embeddings for "Books like this")

Free tier: 50M tokens total (one-time, not monthly).
Hit it when: 50M tokens ≈ 12M books embedded -- effectively never for our scale.
Scale: $0.06/M tokens after the free pool. Even 100k books = ~600M tokens = $36 one-time.

Stripe

No free or paid plan -- it's per-transaction. Standard online: 2.9% + 30¢ per successful charge.
For Plus at $4: Stripe takes $0.42; we keep $3.58.
For Pro at $12: Stripe takes $0.65; we keep $11.35.
Action: nothing until volume justifies a custom rate. Volume-based discounts available by emailing Stripe sales when you're past ~$80k/month processed.

GitHub

Free tier (Personal): unlimited private repos, unlimited collaborators, 2,000 Actions minutes/month, 500 MB Packages.
Hit it when: heavy CI/CD via Actions. We deploy via Vercel CLI, so Actions usage is zero for now.
Scale: GitHub Team at $4/user/month adds protected branches, code review enforcement, more Actions minutes.

Name.com

Free tier: n/a; annual fee on the domain (~$10/yr for .com).
Renewal: enable auto-renew now so we don't lose the domain through inattention. Better: transfer to Cloudflare Registrar -- registers at-cost (no markup), still runs through Cloudflare DNS for free.
Action: 1 year before expiry, click Domain → Transfer to Cloudflare, follow the wizard.

"If we hit it tonight" checklist

In the order they're most likely to bite first:

Resend free emails (3k/mo, 100/day) -- upgrade to Pro at $20/mo from the dashboard. Keep the same API key.
Supabase free DB (500 MB) -- upgrade to Pro before public launch regardless, for backups.
Vercel free bandwidth (100 GB) -- upgrade to Pro at $20/user/mo.
Google Cloud billing not enabled -- enable it once for both Gemini and Google Books to avoid 1k/day caps. Free credit ($300 for 90 days for new accounts) absorbs early use.
Anthropic tier promotion -- automatic with spend; nothing to do.
Cloudflare R2 -- only matters once we move photos out of Supabase Storage. ~3 days lead time to migrate photos.

Each upgrade is a credit-card add inside the provider's dashboard. No code changes needed for any of them; the env vars are the same.