Every cost figure Claude Code shows a developer, the Total cost line in /usage, the status line's cost field, the numbers OpenTelemetry exports, is computed locally from token counts at Anthropic's list price by default. That's a problem the moment an organization pays something other than list price: a contracted discount, negotiated per-model rates, whatever the deal actually is. The developer sees one number; the invoice says another. modelPricing, a managed setting added in Claude Code v2.1.243 (25 August 2026), closes that gap by changing what Claude Code reports, not what Anthropic charges.
What it actually changes, and what it doesn't
This is worth being precise about, because it's easy to misread modelPricing as a billing control. It isn't. Anthropic's own documentation is direct about this: the setting changes what Claude Code reports, not what Anthropic charges. Nothing about actual billing moves when you set it. What moves is every developer-facing cost figure inside Claude Code itself, so that a team working under a contracted rate sees numbers that actually match their invoice, rather than a list-price estimate that's systematically wrong in the same direction every time.
That distinction matters for how you use the setting. Get the rates wrong, and Claude Code will report a confidently incorrect cost that still doesn't reflect what you're billed either way, it just replaces one wrong number (list price) with another wrong number (a mistyped contracted rate). The setting doesn't validate the numbers against anything; it trusts what you enter.
The two levers: multiplier and overrides
Anthropic's manage costs documentation describes two ways to configure the rates, usable separately or together:
multiplier: a flat percentage off list price, applied uniformly across every model. This is the right tool when a contract discounts everything the same way, an across-the-board 15% off list price, for instance, rather than negotiating model by model.overrides: a per-model list of rates for models whose pricing differs from a flat discount, listing each model's four per-token rates individually rather than deriving them from a single multiplier. Claude Code's own/usageoutput already breaks a session's cost down into four token categories per model, input, output, cache read, and cache write, andoverrideslets you set contracted rates for those same four categories per model rather than accepting whatever the multiplier would produce.
You can set multiplier alone for a purely proportional discount, list overrides alone for a handful of models with individually negotiated rates and nothing set for the rest, or combine both: a baseline multiplier for most models, with specific overrides for the ones whose contract terms differ from that baseline. Anthropic's settings reference carries the exact key names and a paste-ready example; the mechanism described here is the shape confirmed on the costs documentation page, worth reading directly before writing the JSON yourself rather than guessing at field names from a summary.
Why it's managed-only
modelPricing is scoped to managed settings exclusively: server-managed settings, an MDM policy, managed-settings.json, or a policy helper program. Claude Code ignores the key entirely if it turns up in user, project, or local settings, or in a --settings file passed on the command line. An individual developer can't set their own contracted rate, deliberately, since the rate is an organizational fact (what your company actually negotiated with Anthropic), not a personal preference, and letting any individual session claim a discount rate would make the reported figures meaningless as a source of truth.
Setting it up
The rollout has three steps, and none of them happen automatically:
- Take the rates from your contract. Claude Code doesn't fetch them from the Claude Console or anywhere else; there's no API call that pulls your actual contracted pricing into the setting for you. You enter the numbers by hand, from the contract itself, and you're responsible for updating them when the contract changes. A stale rate reports a stale cost indefinitely, with no warning that it's out of date.
- Write the setting, using
multiplier,overrides, or both, following the exact shape in themodelPricingsettings reference entry. - Deploy it through managed settings: server-managed settings, an MDM policy,
managed-settings.json, or a policy helper program. This is the step that actually gets the setting into developers' sessions; writing the JSON correctly does nothing until it's delivered through one of these managed channels.
Confirming it took effect
Run /usage in a session that has received the managed settings. When a modelPricing table is in effect, the Session block's Total cost line carries an explicit note: at your organization's configured rates. That note is the confirmation signal; without it, either the session hasn't picked up the managed settings yet, or the deployment channel isn't one Claude Code reads as managed in the first place.
Worth remembering: the figures /usage shows are still estimates, not an invoice, whether they're computed at list price or at your configured rates. modelPricing makes the estimate track your actual contract more closely; it doesn't turn /usage into a billing statement. For that, Anthropic points to the Usage page in the Claude Console as the authoritative source.
What stays at list price regardless
One place modelPricing deliberately doesn't reach: the per-million-token prices shown in the /model picker. Those stay at Anthropic's list price no matter what your organization's modelPricing table says, since the picker's figures describe the model catalogue generally rather than any one organization's contract. Only the cost figures tied to an actual session's usage, /usage, the status line, and OpenTelemetry exports, reflect the configured rates.
A worked example
Say an organisation has negotiated a flat 20% discount off list price across every model. Claude Opus 5 lists at $5 per million input tokens and $25 per million output tokens. With a multiplier reflecting that 20% discount configured in modelPricing, a developer's /usage session block would report Opus 5 usage at the discounted rate, roughly $4 and $20 per million tokens respectively, rather than the $5 and $25 list figures, with the Total cost line carrying the at your organization's configured rates note confirming the table is active. If that same contract separately negotiated a different, non-proportional rate for one specific model, an overrides entry for just that model would report its own contracted rate while every other model continues to use the flat multiplier. Anthropic doesn't publish the exact JSON keys in the portion of the settings reference reachable from here, so treat the dollar figures above as illustrative of the mechanism, not a literal example to copy; get the exact field names from the settings reference page itself before writing the configuration.
Where modelPricing does and doesn't apply
modelPricing is meaningful only where usage is actually billed per token in the first place. Anthropic's cost-management documentation splits organisations into three billing shapes: Claude for Teams or Enterprise, where each member draws from a per-seat allowance rather than being metered in dollars for usage inside that allowance; the Claude Console, where an API organisation is billed per token through workspaces; and cloud providers (Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry), billed per token to your cloud account directly. modelPricing targets the second and third cases, where a per-token contracted rate genuinely exists to report against. On a Teams or Enterprise seat, usage inside the seat allowance isn't metered in dollars at all, so there's no list-price figure for modelPricing to correct in the first place; a spend report on those plans only starts showing dollar figures once a member draws on usage credits past the seat allowance, which is billed separately.
Who this is actually for
modelPricing only matters once an organization is paying something other than list price and wants its developers' day-to-day cost visibility to reflect that. A solo developer on a Pro or Max plan has no contracted rate to configure in the first place, since subscription usage isn't metered per token the way API and cloud-provider billing is; /usage on those plans already shows plan usage bars rather than a dollar figure for that reason. This is squarely an API-organization or cloud-provider setting, the kind an administrator manages through workspace spend limits and the Console's own usage reporting, with modelPricing closing the gap between what the Console shows an admin and what an individual developer sees inside their own terminal.
Where it fits with Claude Code's other cost settings
modelPricing sits alongside promptCacheTtl and subagentPromptCacheTtl, covered in Claude Code's promptCacheTtl setting explained, and the ANTHROPIC_DEFAULT_MODEL environment variable, as part of a small cluster of settings for managing spend across a fleet rather than a single session. None of them substitute for the others. Pinning a default model controls which model, and therefore which per-token rate, new sessions actually use. The cache TTL settings control how much of a request gets reprocessed at all, which affects the token count everything else is computed from. modelPricing sits downstream of both: it doesn't change what happens during a session, only how the resulting token counts get translated into a dollar figure once the session is done.
Troubleshooting
/usage still shows list-price figures after deploying modelPricing. Check that the setting was actually delivered through a managed channel rather than a user or project settings file, which Claude Code ignores for this key specifically. Also confirm the session in question has received the managed settings at all, using /status to inspect where its settings are actually sourced from.
The rates in /usage don't match the actual invoice. modelPricing trusts whatever numbers you entered; it doesn't validate them against Anthropic's own records. Re-check the values against the current contract, since Claude Code has no way to flag a stale or mistyped rate on its own.
A developer asks why the /model picker's prices don't match /usage. That's expected. The picker always shows list price; only /usage, the status line, and telemetry reflect a modelPricing table. The two are answering different questions, the model catalogue's general pricing versus this organization's actual contracted cost.
Only some models show the configured rate; others still show list price. This happens when overrides lists specific models without a multiplier covering the rest. Models not named in overrides, with no multiplier set, fall back to list price, since there's nothing telling Claude Code otherwise for that model.
Where to go next
For the settings deployment mechanism modelPricing depends on, see Claude Code's managed settings documentation. For the cache-lifetime settings that sit alongside it in the same cost-management cluster, see Claude Code's promptCacheTtl setting explained and, for the newer per-agent control, Claude Code's experimental.cacheTtl frontmatter field. Browse the rest of this site's Claude Code coverage at getclaudeskills.com/platforms/claude-code.
Verified 29 August 2026 directly against Claude Code's manage costs documentation at code.claude.com/docs/en/costs, read in full, including the "Report spend at your contracted rates" section that describes the multiplier and overrides mechanism, the managed-only scope, and the /usage confirmation note. The settings-reference page's full modelPricing JSON schema section did not load in full from this environment; the article describes the mechanism the costs page confirms rather than an invented schema.
