Skip to content

SOP: Claude Code Plan Usage vs. API Billing

Home / Guides & Runbooks / SOPs / Claude Code Plan vs. API Billing

Purpose — Ensure Claude Code usage bills against the intended source (your subscription plan or your Anthropic API key), and switch between them deliberately.

When to use — Setting up Claude Code, hitting a plan quota limit, or unsure which account is being charged.

Background

  • Claude Code uses one authentication method at a time.
  • There is no automatic fallback from plan to API. When your plan quota runs out, you are blocked until the reset window — it does not silently start charging your API key.
  • Switching between plan and API is a manual step (change env, restart).

How auth is chosen

Claude Code picks its auth source in this order:

  1. ANTHROPIC_API_KEY is set (env var, or a settings.json env block) → all usage bills your API key. Your subscription is skipped entirely, even if you're logged in.
  2. No API key set, logged in via subscription (/login) → all usage counts against your plan. Hit the limit → blocked until reset.

Key point: the API key always wins. If it's set anywhere Claude Code reads, /login has no effect on billing.

Common gotcha: the key hides in settings.json

An ANTHROPIC_API_KEY in ~/.claude/settings.json is injected into every session, so you're on API billing without realizing it:

{
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-..."
  }
}

To use your plan, remove that env block and restart Claude Code. Check which auth is active with /status.

Note

A running Claude Code process keeps whatever env it started with. Any change (removing the key, unset, etc.) needs a restart to take effect.

Steps

  1. Make sure ANTHROPIC_API_KEY is not set:
  2. not in your shell (echo $ANTHROPIC_API_KEY prints nothing)
  3. not in ~/.claude/settings.json (no env block with it)
  4. not in ~/.zshrc / ~/.bashrc / ~/.zshenv / profile files
  5. /login with your subscription account.
  6. /status → confirms subscription auth.

Switch to API when the plan runs out

  1. In your terminal: 
    export ANTHROPIC_API_KEY=sk-ant-...
  2. Restart Claude Code.
  3. Now billing goes to the API key.

Switch back to plan

  1. unset ANTHROPIC_API_KEY (and remove it from any profile / settings.json).
  2. Restart Claude Code.

Verification

State Billing At quota limit
ANTHROPIC_API_KEY set (env or settings.json) API key Keeps working (API rates)
No API key + subscription login Plan Blocked until reset — no auto-fallback

Check current auth any time with /status.

Security notes

  • Never hardcode the API key in settings.json if you can avoid it — it's easy to forget it's there, and it silently overrides plan billing.
  • Treat the key like a password. If it ever prints to a terminal, gets committed, or lands in editor history, rotate it at https://console.anthropic.com → API keys.
  • Prefer setting ANTHROPIC_API_KEY in your shell only for the session you need it, then unset it.