← Blog

Claude Opus 5.5 migration from Opus 4.8: the cost meter, thinking and refusal changes a production kit needed

Moving a Next.js kit from Claude Opus 4.8 to Opus 5.5: 20% cheaper per token, a cache meter that would have overbilled 90%, and thinking that stays on.

I moved the kit's default model from Claude Opus 4.8 to Claude Opus 5.5 on November 9. Swapping the model ID took a minute. The Claude Opus 5.5 migration took the rest of two days, because the parts that broke were not the ones that throw errors: the cost meter, which helpers now think, and a homepage label no search found. Here is what changed, with the numbers from running the kit's own cost function before and after.

What the Claude Opus 5.5 migration does to real usage costs

Opus 5.5 lists at $4 per million input tokens and $20 per million output, against $5 and $25 for Opus 4.8, so most traffic gets 20% cheaper. Cache reads are the exception: Opus 5.5 bills them at $0.20 per million, a twentieth of its input price, where earlier models bill a tenth. I ran the same usage shapes through the old costUsd (from the commit before the switch) and the new one:

  • A chat session, 30,000 tokens in and 4,000 out, no cache: $0.2500 on Opus 4.8, $0.2000 on Opus 5.5, 20% less.
  • A 2,000-token cached system prompt plus 500 tokens in and 800 out: $0.0235 to $0.0184, 22% less.
  • A 900,000-token document read from cache, 1,000 tokens out: $0.4750 to $0.2000, 58% less.
  • The same document written to the cache: $5.6500 to $4.5200, 20% less.

Cache-heavy long-context traffic gains the most, which changes the math in the 1M-context tradeoff more than anything else in the release.

The meter bug a price edit would have shipped

The old cost function priced cache tokens as fixed multiples of the input price:

// before: right for every model the registry listed, until Opus 5.5
usage.cacheReadTokens * m.inputPerMTok * 0.1 +
usage.cacheCreationTokens * m.inputPerMTok * 1.25

// after: each model carries its own cache prices
usage.cacheReadTokens * m.cacheReadPerMTok +
usage.cacheCreationTokens * m.cacheWritePerMTok

If I had only changed the registry entry to $4 and $20 and kept the multipliers, the meter would have billed cache reads at $0.40 per million. On the four shapes above, that version comes out at $0.2000, $0.0188, $0.3800 and $4.5200. The uncached and cache-write shapes are exactly right. The small cached prompt is 2% high, small enough to pass any spot check. The 900,000-token cached read is 90% high, on the requests where users most need to trust the number. Every model in the registry now has cacheReadPerMTok and cacheWritePerMTok fields, and the prompt caching math was updated with the new rate.

The demo's cost panel had the same assumption in its markup: a label that read "Cache read (0.1×)". It now reads the rate from the registry, so Opus 5.5 shows 0.05×.

Thinking, effort and refusals

None of these made a kit request fail, which is why they are easy to miss. All three are in the Opus 5.5 migration notes in Anthropic's API reference.

  • Thinking is always on. On Opus 4.8 a request with no thinking field ran without thinking. On Opus 5.5 it thinks, and { type: "disabled" } returns a 400. The kit's text, stream and tool helpers already sent { type: "adaptive" }, so they behave as before. The structured-output helper sends no thinking field, so it went from not thinking to thinking, inside the same 16,000-token max_tokens. The thinking parameter guide covers the per-model rules. Raising that limit past 21,333 on a non-streaming call hits the SDK's streaming requirement.
  • Effort defaults to medium. Earlier Opus models defaulted to high. The kit never sets output_config.effort, so every route now runs at medium unless you set it.
  • Refusals are a stop reason to plan for. Opus 5.5's safety classifiers are broader. The chat stream now records usage and then sends an error event when stop_reason is refusal, and the tool loop throws, as generateText already did.

Three of Opus 5.5's breaking changes did not touch the kit. It never forces tool_choice, which now returns a 400. It never disables thinking. And its tool loop passes the assistant's content back unmodified, which is what the new rule about replaying thinking blocks requires. I had no API key in the build container, so none of this was checked against live thinking-token counts; the behavior comes from the migration notes and the code paths.

Things that bite

  • A search for the old name misses split text. I replaced every "Opus 4.8" a grep found, and the homepage still said it the next day: its spec block renders "Claude", "Opus" and "4.8" as three separate spans for an animation. Search for the version number on its own, then look at the rendered page.
  • Plan feature strings are hand-written. The pricing cards' model list is a literal string, so the plans needed two edits each, the IDs and the text, as described in the pricing page drift post.
  • Old clients get clamped, not errored. A request that still names claude-opus-4-8 fails the chat route's isModelId check and falls back to the plan's default, now Opus 5.5.
  • Old usage rows keep their cost. Cost is computed when a request is recorded and stored as integer micro-USD, so history stays priced at Opus 4.8 rates. Nothing recomputes it from the stored model ID, which matters because that ID is no longer in the registry.
  • Your own articles go stale. Eleven posts on this blog quoted Opus 4.8 prices or behavior. They were recomputed with the new cost function and carry an updated date.

Shipwright, the Next.js and Claude starter kit this blog documents, keeps model IDs and prices in one registry, so most of this migration was one file plus the follow-ups above. You can see per-request cost in the live demo.