claude-code - 💡(How to fix) Fix [DOCS] Billing documentation is materially misleading: "standard API rates" implies token monitoring is sufficient, but documented token costs are only part of the bill [1 participants]

Describe the problem

The billing documentation — including the extra usage pricing statement "Extra usage is billed at standard API rates" — is technically accurate but creates a false impression that users can manage their costs by watching token consumption. In practice, the costs that dominate real-world bills are cache-related, not directly tied to visible token activity, and are entirely absent from the documentation.

Specifically undocumented or insufficiently explained:

1. Per-turn cache read accumulation. Every API call re-bills the user for the entire accumulated context at the cache-read rate. At ~650K tokens and $0.50/MTok (Opus 4.7), that is ~$0.33 per turn regardless of what was asked. This compounds across hundreds of turns in a long agentic session and has nothing to do with the complexity of the user's prompts.

2. The 200K pricing cliff. Once input exceeds 200K tokens, ALL tokens in that request are billed at the extended-context rate (2× input, 1.5× output) — not just the tokens above the threshold. Crossing from 199K to 201K tokens doubles the entire request cost. This cliff is not mentioned on the pricing page.

3. Compaction costs — including invisible ones. Compaction events write the full accumulated context to cache at the cache-write rate (~$4 per event at typical session sizes) and fire automatically. Some compaction events are not visible to the user at all — they can occur inside sub-agent invocations with no indication in the main session UI. Users have no warning they are coming, no visibility into their cost, and in some cases no awareness they occurred.

4. The tooling, documentation, and marketing materials all materially understate these costs. The running token counter in Claude Code Desktop significantly undercounts actual consumption (#55121) and does not surface cache read/write consumption at all (#55133). The pricing documentation implies that token rates are the primary cost signal. Marketing materials describing plan tiers reinforce this framing. The combined effect is that a user who has read the documentation, enabled extra usage, and is actively monitoring the token counter is still working from a model of their costs that can be wrong by an order of magnitude or more.

A concrete example: a user on Max 5 with Opus 4.7 (1M context) enabled extra usage near the end of a 4-hour session — deliberately limiting themselves to discussion-level work, explicitly avoiding intensive tasks. In under 50 minutes they were charged $21 in extra usage. The session's context had accumulated to ~650K tokens during the prior session; at that size, every turn cost ~$0.33 in cache reads alone before any response was generated. Two automatic compaction events during the extra-usage window added ~$4 each. None of this was visible in the token counter or explained in the documentation. The true cost breakdown was reconstructed only through manual analysis of raw JSONL session records — a path not available to most users and highly disruptive even for those who know the files exist.

Community analysis independently corroborates the scale: one user found cache reads consumed 97.7% of session costs, with $1.47 in expected API cost producing a $64.98 bill — a 44× ratio (source). Other cost factors (e.g. MCP loading overhead) may also be material but are similarly undocumented; the cache issues alone are large enough to dominate.

Describe the solution you'd like

The billing/pricing documentation should:

• Explicitly state that cache reads and writes are billed per API call proportional to accumulated context, not per session
• Document the 200K extended-context pricing cliff and its all-or-nothing threshold behavior
• Explain that compaction events are automatic, sometimes invisible, and constitute discrete large cache-write charges
• Include a worked example showing how a long agentic session's actual cost is dominated by cache activity, not prompt/response size
• Not imply that the token counter is a reliable cost management tool until #55121 and #55133 are resolved

Prior art

#28723 is related but is fundamentally a complaint about the service behavior — quota depleting faster than expected. This issue is specifically about the documentation failing to explain the cost mechanics that cause that behavior. Fixing the docs doesn't fix #28723, and fixing #28723 doesn't fix the docs.