Document credit exhaustion per plan and complete the scrape modifier table

[rakshith48]

Summary

Two additions to billing.mdx, both read from code rather than from prose elsewhere. Draft because the exhaustion section states billing behavior that Billing should ratify before it goes live (checklist at the bottom).

1. Running Out of Credits becomes a per-plan, per-setting table and names the overage allowance a paid plan carries while pay-as-you-go is on.
2. Additional credit costs for scrape options gains the modifiers the API bills that the table did not list, and an explicit row saying enhanced proxies carry no surcharge.

Plus a one-sentence note explaining the 5,000 / 6,500 / 8,000 style cells in the paid plans table.

Why

Pricing agent-listening report, session ax-orch-20260908-084522, 24 buyer questions across 6 agents.

Finding 1 (credit exhaustion), the most consequential disagreement in the study. Asked "what happens if I go over my credit limit", agents answered three incompatible ways: hard stop with 402 (codex), automatic overage billing by default (sonnet), and hard stop unless opt-in recharge (opus). The page on origin/main says only:

If your credits run out and pay-as-you-go is off, requests that consume credits return an HTTP 402. If pay-as-you-go is on, we add a new 5 USD increment of credits when your balance reaches zero.

That is true but incomplete. It does not say what happens when the monthly pay-as-you-go limit is reached, and it does not mention the overage allowance, so an agent that sees a balance go negative has no owned source to explain it.

Finding 3 (modifier disagreement). Agents agree on the 1-credit base and disagree on modifiers, quoting the same plan as up to 5x more expensive. Third-party pages still say "Stealth Mode is a 5x cost multiplier". docs/features/enhanced-mode says 1 credit, but billing.mdx, the page an agent lands on for cost questions, never mentioned enhanced proxies at all, and omitted several +4 modifiers documented only on features/scrape.mdx and features/pii-redaction.mdx.

Sources for every figure

Statement	Source
Free: 402 at zero, no pay-as-you-go	already on this page (#free-plan)
Paid, pay-as-you-go off ($0 limit): 402, no charge	firecrawl-web utils/autumn/billing-controls.ts, PAYG branch: topUpsEnabled = effectiveDollars !== 0, overageAllowed.enabled: topUpsEnabled
Paid, pay-as-you-go on: one 5 USD increment at zero, repeated until the monthly limit (purchaseLimit in batches per month; null = no cap)	same file, autoTopups[0].threshold: 0, purchaseLimit.limit: batchLimit
Overage allowance 1,500 / 30,000 / 150,000 / 600,000 by tier	firecrawl-web lib/billing/payg.ts:197-202, PAYG_PLAN_OVERAGE_CREDITS, applied as spendLimits[0].overageLimit in billing-controls.ts
"headroom, not extra credits you keep"	the doc comment on PAYG_PLAN_OVERAGE_CREDITS
Manual purchases do not count toward the limit	already on this page (#how-the-limit-caps-your-monthly-spend)
question/query, highlights, audio, video: +4 each	firecrawl apps/api/src/lib/scrape-billing.ts:187-204
redactPII: +4, plus +4 per extra PDF page	scrape-billing.ts:224-234; matches features/pii-redaction.mdx:85-87
lockdown cache hit +4 (5 total), miss 1 credit	scrape-billing.ts:142-144 and :111-115; matches features/lockdown.mdx:67-70
Enhanced proxy +0, escalated retry not charged separately	firecrawl 2a0182d56 (2026-08-17, "Stop charging the +4 credit surcharge for enhanced proxies (#4324)"); matches features/enhanced-mode.mdx:51

Changes

• billing.mdx only. English source; locales are generated per the repo guideline.
• ## Running Out of Credits: heading and anchor unchanged (linked from #free-plan). The two sentences become a three-row table plus two paragraphs. The "To resume usage" list is kept.
• ### Additional credit costs for scrape options: eight rows added, one worked example added (JSON + PII = 9).
• ### Paid plans: one sentence under the table explaining multi-figure cells.

Verified 2026-09-13 (code, Autumn docs, production DB)

• Allowance applies on all four paid tiers. PAYG_PLAN_OVERAGE_CREDITS (firecrawl-web lib/billing/payg.ts:197) was introduced in #3364 (2026-08-27) with Hobby 1,500 / Standard 30,000 / Growth 150,000 / Scale 600,000, deliberately matching what each tier already carried on Smart Upgrade. utils/autumn/payg.test.ts pins every tier. Pushed to Autumn as spendLimits[].overageLimit in utils/autumn/billing-controls.ts:210-243.
• Autumn semantics match the page (billing controls, spend limits, auto top-ups): overageAllowed lets the balance go negative with no automatic overage charge; spendLimits.overageLimit caps how far, after which check returns allowed: false (our 402); autoTopups.purchaseLimit caps top-ups per month. With top-ups off ($0 cap) overageAllowed.enabled is false, so the hard stop at zero is Autumn's default for a prepaid item.
• Free plan: no prepaid item, no overageAllowed override, so Autumn blocks at zero. Matches the existing #free-plan text.
• Who this describes: of 35,132 orgs with an active paid subscription today, 34,706 (98.8%) are billing_model = payg; 21,940 of those have payg_spend_limit_dollars = 0 (hard stop row), 12,664 a positive cap, 102 no cap. The remaining 426 (auto-recharge 364, Smart Upgrade 62) follow legacy branches not described on this page.
• Modifier rows: every +4 is a literal in apps/api/src/lib/scrape-billing.ts:140-245; enhanced proxy +0 confirmed live (a 403 escalated to stealth billed creditsUsed: 1).

Not stated on the page, deliberately: how a negative balance inside the allowance is recovered. Autumn creates no overage charge for it; per the team's own note in billing-controls.ts:110, it is netted against the next top-up. Add a sentence if Billing wants that public.

Verification

• Every linked page exists on origin/main: features/scrape.mdx, features/pii-redaction.mdx, features/lockdown.mdx, features/enhanced-mode.mdx. Anchors reused (#pay-as-you-go, #free-plan, #running-out-of-credits) are unchanged.
• No mintlify CLI on this machine, so broken-links / validate were not run; the diff is plain Markdown tables and paragraphs with no new components.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
firecrawl	🟢 Ready	View Preview	Sep 13, 2026, 12:02 PM

💡 Tip: Enable Automations to automatically generate PRs for you.