Claude Code: subscription or API billing?

Claude Code runs on either a Claude subscription login or Claude Console API billing, and for a single developer doing hands-on interactive work the subscription is almost always the right default: flat fee, no per-token anxiety, and Claude Code included. API billing is the right answer when software rather than a person is driving, when you need per-user reporting and spend caps, or when the work is sporadic enough that idle days should cost nothing.

How Claude Code decides which one you are on

This is the part that surprises people, because Claude Code does not ask every session. It picks a credential by precedence, and an environment variable quietly outranks the login you did on purpose.

The documented order, from highest to lowest:

1. Cloud provider credentials, when CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX, or CLAUDE_CODE_USE_FOUNDRY is set.
2. ANTHROPIC_AUTH_TOKEN, sent as a bearer token, for gateways and proxies.
3. ANTHROPIC_API_KEY, sent as the API key header. This is the usual cause of an accidental API bill.
4. apiKeyHelper, a script that returns a key, for rotating credentials.
5. CLAUDE_CODE_OAUTH_TOKEN, the long-lived token from claude setup-token.
6. Anthropic profile and federation credentials.
7. Subscription OAuth credentials from /login, the default for Pro, Max, Team, and Enterprise.

Two commands tell you where you actually are. /status shows a Login method row for your subscription account, and adds an API key row when a key is in use. /usage shows plan usage bars and reset times on a subscription login; if all you see is a session cost figure and no plan bars, you are on API billing. That session dollar figure is computed locally at list price, so on a subscription it is informational rather than a bill.

If you meant to be on your subscription and are not, run unset ANTHROPIC_API_KEY and check /status again. In interactive mode there is also a "Use custom API key" toggle in /config, shown only while that variable is set. In non-interactive mode with -p, a present key is always used, no prompt.

What actually changes when you switch

Same models, same Claude Code, different everything else around it.

• Metering. A subscription meters a rolling five-hour session window plus weekly caps (one across all models, one for Opus). The API meters dollars per token, with no windows and nothing that resets.
• Predictability. A subscription is a fixed number on your card and a variable amount of work. The API is a fixed price per unit of work and a variable number on your card. Which uncertainty you prefer is a real decision, not a rounding error.
• What "rate limit" means. On the API you have requests per minute, input tokens per minute, and output tokens per minute, set by your organization's usage tier, and exceeding one returns a 429 with a retry-after header. On a subscription there is no per-minute quota to tune; you have windows. The two systems are covered side by side in Claude rate limit errors.
• Org controls. API billing gives you Console workspaces, spend limits, and per-user reporting. Authenticating Claude Code with a Console account creates a workspace named "Claude Code" for centralized tracking, and you can set a workspace rate limit on it so agent traffic does not crowd out production.
• Seats. On Claude for Teams and Enterprise, each member's Claude Code usage draws from a per-seat allowance on a rolling five-hour window and a weekly window, shared with Claude chat. That is a subscription shape with admin tooling on top, not API billing.
• Prompt cache lifetime. An hour on a subscription; five minutes by default on an API key or cloud provider unless you choose the TTL yourself. On long agentic sessions with gaps, that difference shows up in the bill.

Three usage patterns, and which path fits

Rather than a table of invented numbers, here are the three shapes people actually have. Price your own volume at current API rates before committing either way.

1. The daily driver. Claude Code is open most working days for hours at a time, one person, interactive. This is where metered billing hurts most: agentic loops resend the accumulated context every turn, so token volume compounds with session length in a way that surprises people the first time they see the invoice. A flat fee removes that entirely, and the heavier you are, the more work per dollar you get. Pick the subscription, and see Max 5x vs 20x for the tier.

2. The occasional user. A few sessions a week, sometimes none. Metered billing means quiet weeks cost nothing, which is the one thing a subscription can never do: on a flat plan, a light week is capacity you paid for and did not use. If your usage is genuinely spiky and low, the API can be the cheaper choice. Claude Pro vs API: the real cost works through that comparison.

3. The pipeline. Scheduled jobs, CI checks, an agent running against a queue, several developers on one team. Here it stops being a cost question. You need keys, logs, workspaces, spend caps, and reproducible per-user attribution, which live on API billing or on a Teams and Enterprise plan. Running shared automation off one person's personal subscription creates an attribution problem long before a cost problem.

CI and automation: which credential belongs there

Claude Code does support subscription-backed automation. claude setup-token opens the same browser authorization flow as /login and prints a one-year OAuth token that you set as CLAUDE_CODE_OAUTH_TOKEN in environments where an interactive browser login is not possible. It authenticates with your Claude subscription and requires a Pro, Max, Team, or Enterprise plan.

The caveat is that the token is yours. It draws on your personal windows, it can only make model requests, and when it expires or the person leaves, the pipeline stops. For a personal cron job or a solo side project that is fine and cheap. For anything a team depends on, an API key with a Console workspace and a spend limit is the credential that survives contact with reality, because the billing, limits, and audit trail belong to the organization rather than one login.

One practical note if you script Claude Code: long unattended runs fail differently on each path. On a subscription they pause at a window boundary and resume when it rolls off. On the API they keep going until a spend cap or a 429 stops them. Design the job for whichever failure mode you are choosing.

How to switch, or run both

Switching is a two-minute job in either direction.

• Subscription to API: set ANTHROPIC_API_KEY in your environment and approve it when Claude Code prompts. It outranks your login from that point on.
• API back to subscription: unset ANTHROPIC_API_KEY, then run /login and sign in with your Claude.ai account. Confirm with /status.
• Console without a key: you can sign in to a Console account without creating an API key at all; Claude Code stores the OAuth login as a profile and refreshes it for you.
• Reset everything: /logout removes the stored credential and walks you through login again next launch.

Running both is a legitimate and common setup: subscription for the terminal work you do by hand, an API key for anything unattended. The cleanest way to hold both is per-shell environment, so the variable is set only in the window that runs the automation. Just do not expect one to subsidize the other; as does Claude Pro include API credits spells out, neither funds the other.

The cheapest compute you own is the capacity you already bought

Here is the asymmetry that should shape the decision. API credits sit there until you spend them. Subscription capacity does not: it is a ceiling, not a balance, and whatever you have not used when a window resets is gone. If you keep a subscription for your daily work, most weeks end with real, paid-for headroom that expires quietly. That surplus is the cheapest compute you have access to, because it is already spent.

Tokens for Good is one thing to point it at. Your Claude Code claims a queued nonprofit, researches its real-world impact against a fixed methodology with citations, and submits a structured report, then stops. Every organization is researched twice by independent contributors, then validated, consolidated, scored deterministically, and human-reviewed before it reaches the public directory. It runs on the subscription you already pay for with no separate API cost, and it can run on a schedule in the background. "Tokens" here means AI model tokens, not crypto: no coin, no wallet, no blockchain. See how the research works, read what Tokens for Good is, or set it up from the docs in about a minute.

Frequently asked questions