Policy and documentation checked on November 5, 2026. All terminal examples use Bash, for macOS, Linux and development environments running Bash.

After purchasing Max, Ultra or Team, you need to link the included API credits to a Claude Console organization before using them in your own programs or agents.

Work through the process in this order:

Check eligibility → link a Console organization → inspect promotional funds → create an API key → send a small request → verify the organization and usage records → configure claude -p.

The essential point is that the subscription account, Console organization, API key and actual billing route must correspond. Receiving a model response establishes that a request succeeded. You still need to check which organization and balance funded it.

1. Check how much you can claim, and who can claim it

The current monthly API credit program provides:

Plan or seatMonthly API creditWhere it belongs
Max$100One linked Console organization
Ultra$200One linked Console organization
Team Standard$20 per seatPooled across the team
Team Premium$100 per seatPooled across the team
Team totalUp to $500One organizational balance pool

For example, three Standard seats and two Premium seats have a nominal monthly grant of:

3 × 20 + 2 × 100 = 260 USD

Ten Premium seats are still subject to the $500 monthly cap for the whole team.

Two conditions apply before claiming: the plan must be active and in good standing, and a new subscriber must have spent seven days on an eligible plan. Subscriptions purchased through iOS or Android can participate, but credits must be claimed on the web. You do not need to add a payment card to Claude Platform first.

Official monthly credit policy · Platform claiming and credit-application guide

Also check permissions on both sides:

WhereRequired identity or role
Max / Ultra subscriptionThe subscriber
Team subscriptionPrimary Owner or Owner
Receiving Console organizationOwner, Admin or Billing

Seven days is the eligibility threshold for claiming API credits. It cannot be used to infer when Ultra automatic verification will finish.

2. Link a Console organization on the web to claim credits

For Max and Ultra, open:

For Team, an Owner or Primary Owner opens:

Follow these steps:

  1. Find the API credits section.
  2. Click Link organization.
  3. Select the Claude Console organization that should receive the credits. If none exists, follow the page’s creation flow.
  4. Check the organization’s name and intended use.
  5. Read the relevant terms and confirm linking.
  6. Open Billing in Console and check that the credits have been posted.

Choose the organization carefully before linking. A plan can link to only one Console organization, and each Console organization can receive this grant from only one plan. You cannot change the link yourself afterward; contact support to change it.

Platform claiming and credit-application guide

Team members do not each need to claim again. An authorized owner links the organization, and members using API keys within it share the balance afterward.

If the claim option is missing, check the plan, time subscribed, current signed-in identity and roles on both sides before contacting official support.

3. Where to check the balance, and which figures matter

After claiming, open:

Start with Promotional credits and record:

  • The amount of the grant;
  • The available balance currently displayed;
  • The expiration date;
  • The Console organization currently selected.

Then check the purchased balance and Auto-reload settings separately.

Monthly credits are used before purchased credits. Unused credits expire with their applicable period and do not roll over. Annual subscriptions also receive monthly grants. Pay particular attention to auto-reload: it triggers from the purchased balance, so a recharge can occur even while promotional credits remain.

Platform claiming and credit-application guide

Keep these three kinds of figures separate when reconciling costs:

FigureWhat it answers
Billing balances, grant postings and expiration datesHow much remains, where it came from and when it expires
usage returned by a requestHow many tokens this request used
Usage / Cost reports or CLI cost estimatesWhere consumption occurred, and its estimated or actual cost

usage is not a dollar balance. Nor does the CLI’s total_cost_usd establish that the cost has already been deducted from promotional funds. Current Cost Analytics cost fields are calculated before credit deductions, and reports can update with a delay.

Usage and Cost Analytics

4. Create an API key in the correct workspace

Open:

For a personal exercise, use this approach:

  1. Confirm that the current Console organization is the one receiving the grant.
  2. Click Create key.
  3. Enter a recognizable name, such as monthly-credit-demo.
  4. Set an expiration appropriate to your needs.
  5. Select your own account under Linked account to create a personal key.
  6. Choose an ordinary API workspace you are authorized to access, creating a key scoped to that single workspace.
  7. Save the key shown at creation and note the organization, workspace and key name.

The complete key appears only once, at creation. A personal key is suitable for individual development. Shared services or production systems can use a service account according to organizational management requirements.

Create an API key

Two permission details also matter:

  • Permission to claim credits does not imply permission to create a key. The Billing role primarily handles billing and usage; key creation requires the appropriate organization and workspace permissions.
  • Creating a workspace requires an organization administrator. Ordinary members should select a workspace they already have access to. If a button is unavailable, ask an administrator to check roles and membership.

Do not choose the dedicated Claude Code workspace to manually create a practice key. The official explanation says keys in that workspace are managed by the Claude Code sign-in flow.

Console roles and permissions · Workspace management

All examples below use a key scoped to one workspace when created. Current API rules require an additional workspace header for keys not scoped to a workspace. Do not mix the two types of key configuration.

API authentication and versioning

5. Prepare a temporary terminal environment

Practice in a separate terminal first, keeping the key in the current session only.

Start Bash:

bash --noprofile --norc

Then run:

set +x
umask 077

unset ANTHROPIC_API_KEY
unset ANTHROPIC_AUTH_TOKEN CLAUDE_CODE_OAUTH_TOKEN ANTHROPIC_BASE_URL
unset CLAUDE_CODE_USE_BEDROCK CLAUDE_CODE_USE_VERTEX
unset CLAUDE_CODE_USE_FOUNDRY CLAUDE_CODE_USE_ANTHROPIC_AWS
unset CLAUDE_CODE_EFFORT_LEVEL

mkdir -p "$HOME/claude-api-credit-demo"
cd "$HOME/claude-api-credit-demo"

These temporary settings make this exercise explicitly target the first-party API. Organization gateways or provider policies can still constrain company-managed Claude Code. Ask the administrator to investigate if the route is unexpected.

Claude Code authentication and precedence

Next, run the following line separately, paste the key you just created and press Enter. The input will not be echoed:

read -r -s -p 'Paste the linked organization API key, then press Enter: ' ANTHROPIC_API_KEY

After entering it, run:

printf '\n'
export ANTHROPIC_API_KEY

Do not put a real key in article examples, script source or shell history. You do not need to print it with echo to confirm it.

6. Send the first small request with curl

This connectivity example fixes the model to claude-haiku-5-5, limits output and disables thinking. This parameter combination is specific to that model. Check supported parameters again when switching models.

Haiku 5.5 model documentation · Thinking parameter guide

First create the request file:

cat > request.json <<'JSON'
{
  "model": "claude-haiku-5-5",
  "max_tokens": 128,
  "thinking": {
    "type": "disabled"
  },
  "output_config": {
    "effort": "low"
  },
  "messages": [
    {
      "role": "user",
      "content": "Reply only: API connection successful"
    }
  ]
}
JSON

Then send the request:

curl --disable --silent --show-error \
  --connect-timeout 10 --max-time 60 \
  --dump-header response.headers \
  --output response.json \
  --write-out 'HTTP %{http_code}\n' \
  --config - <<EOF
url = "https://api.anthropic.com/v1/messages"
request = "POST"
header = "Authorization: Bearer ${ANTHROPIC_API_KEY}"
header = "anthropic-version: 2026-10-21"
header = "content-type: application/json"
data-binary = "@request.json"
EOF

The command creates two files:

  • response.json: the response body, including content, stop reason and token usage;
  • response.headers: response headers used to check the request identifier, organization, workspace and related information.

The key reaches curl through standard input rather than command-line arguments. --disable is the first option so an existing .curlrc does not change this small test’s behavior.

The current official API uses version 2026-10-21 and supports API keys in Authorization: Bearer. A single-workspace key can omit the workspace-selection header.

API authentication and versioning

Inspect the response body:

python3 -m json.tool response.json

Check these points:

  1. Whether the HTTP status is 200.
  2. Whether content contains text.
  3. Whether stop_reason indicates a normal finish or max_tokens.
  4. The input, output and cache tokens actually reported in usage.

Then extract the response headers needed for verification:

python3 - <<'PY'
from pathlib import Path

wanted = {
    "request-id",
    "anthropic-organization-id",
    "anthropic-workspace-id",
}

for line in Path("response.headers").read_text(
    errors="replace"
).splitlines():
    name, sep, value = line.partition(":")
    if sep and name.lower() in wanted:
        print(name.lower() + ":", value.strip())
PY

Match the returned organization and workspace identifiers with Console records. A successful request, the correct organization and usage in the intended workspace together form the complete verification chain.

7. Use the same credits through the Python SDK

Use the official Python SDK to integrate the API into your own program. Current documentation requires Python 3.10 or later.

Create a virtual environment in the practice directory:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade anthropic

Create call_api.py:

import json
import os
import anthropic

with anthropic.Anthropic(
    api_key=os.environ["ANTHROPIC_API_KEY"],
    base_url="https://api.anthropic.com",
    timeout=30.0,
    max_retries=0,
) as client:
    raw = client.messages.with_raw_response.create(
        model="claude-haiku-5-5",
        max_tokens=128,
        thinking={"type": "disabled"},
        output_config={"effort": "low"},
        messages=[
            {"role": "user", "content": "Reply only: API connection successful"}
        ],
    )

    message = raw.parse()

    for name in (
        "request-id",
        "anthropic-organization-id",
        "anthropic-workspace-id",
    ):
        print(name + ":", raw.headers.get(name, "(not returned)"))

    print("model:", message.model)
    print("stop_reason:", message.stop_reason)

    for block in message.content:
        if block.type == "text":
            print(block.text)

    print(json.dumps(message.usage.model_dump(), ensure_ascii=False))

Run:

python call_api.py

raw.parse() parses the response already received; it does not send another model request. Automatic retries are disabled so the first validation can associate one execution with one request. A production system can later implement retries according to its requirements.

Python SDK documentation

8. Configure claude -p to use these credits

The official documentation specifies an important coverage condition:

You can use the monthly API credits when you run claude -p or the Agent SDK yourself with an API key from the linked Console organization.

Signing in with a Claude subscription still consumes subscription allowances. Runs started by the Claude Code GitHub Action, an IDE extension or Claude Desktop do not qualify for that coverage condition, even with -p.

Official monthly credit policy

Work through this section in an independent system terminal you open yourself, continuing to use the API key configured above.

First check the version:

claude --version

This guide uses the full Haiku 5.5 model ID. The official requirement is Claude Code v2.1.293 or later. If it is missing or older, follow the official installation and update instructions for your installation method.

Claude Code installation and updates · Claude Code model configuration

You can first diagnose the authentication source:

claude auth status

The current JSON output’s authMethod can help identify the credential source, for example api_key, claude.ai or third_party.

However, api_key only indicates that this authentication source was recognized. It does not establish that the key is valid, belongs to the right organization or has received promotional credits.

Claude Code CLI reference

Then run a minimal task:

claude --bare -p 'Reply only: API connection successful' \
  --model claude-haiku-5-5 \
  --effort low \
  --tools '' \
  --max-turns 1 \
  --max-budget-usd 0.10 \
  --output-format json \
  --no-session-persistence > claude-result.json

What the options control:

OptionRole in this exercise
--bareDoes not read OAuth or the system keychain; skips automatic discovery of hooks, skills, plugins, MCP and similar features
-pRuns non-interactively and exits after producing output
--modelSets the model instead of inheriting the everyday session’s selection
--effort lowRequests lower reasoning effort
--tools ''Disables built-in tools to validate text calls first
--max-turns 1Limits agent turns
--max-budget-usd 0.10Sets a client-side estimated-cost threshold
--output-format jsonKeeps a structured result for inspection
--no-session-persistenceDoes not save this session for later resumption

--bare still supports explicitly specified settings and cloud credentials, so the earlier environment checks remain important. No additional MCP, plugins or directories are supplied here.

Also, --max-budget-usd relies on a client-side cost estimate. It is not a hard guarantee that the bill cannot exceed that amount. --max-turns is not a token cap either. Configure Console spending controls before scaling up the task.

Run Claude Code programmatically · Claude Code CLI reference

Inspect the result:

python3 - <<'PY'
import json
from pathlib import Path

data = json.loads(Path("claude-result.json").read_text())

print("is_error:", data.get("is_error"))
print("result:", data.get("result"))
print("estimated_cost_usd:", data.get("total_cost_usd"))
print("usage:", data.get("usage"))
PY

If a field is absent, leave it unknown rather than filling in zero. When a command fails, inspect standard error and the result file too. No output from the parsing step does not establish that no request occurred.

9. Verify that consumption followed the intended route

After the small test, check these items in order:

  1. Correct key ownership: it was created in the Console organization receiving the grant.
  2. Correct workspace: the intended workspace was selected when creating the key, and the identifiers returned by the API match.
  3. Correct surface: the first-party API, or self-run claude -p meeting the official conditions.
  4. Correct usage record: the request’s usage appears under the expected workspace in Console.
  5. Correct balance record: reconcile Promotional credits, purchased funds, grant postings and expiration.

When an organization has both promotional and purchased credits, the platform uses promotional funds first under its rules. You do not add a separate “use promotional credits” parameter to each request.

Reports can update with a delay, and a small request may cost very little. If the interface does not show an obvious change immediately, do not repeatedly rerun it to force a visible change.

Platform claiming and credit-application guide

10. Troubleshoot common problems

SymptomCheck first
API credits option is missingPlan, seven-day eligibility, current signed-in identity and roles on both sides
You can claim, but Create key is unavailableConsole role, workspace membership and key-creation permissions
HTTP 401Whether the key is correct, valid and exported to the current shell
HTTP 403Key, workspace, model or resource access permissions
HTTP 400Read the specific error type; check parameters, version, workspace and relevant spending restrictions
HTTP 402 / billing_errorOrganizational billing, balance and payment status
HTTP 404Model ID, endpoint and resource availability
HTTP 429Distinguish request/token rates from relevant spend caps; inspect the specific error and response information
stop_reason is max_tokensOutput reached its cap; the request may have succeeded without producing complete content
curl works but the CLI does notCLI version, API-key environment, provider/gateway route and organizational policy
The CLI runs but promotional funds show no obvious decreaseCoverage conditions, correct organization, report delays or display precision

Do not attribute every error to an insufficient balance. Conversely, funds remaining do not mean organization spend caps, workspace budgets or rate limits have been removed.

API error reference · Rate and spend limits

Team owners should also assign appropriate workspaces and member permissions to projects and configure spending alerts. The Default Workspace currently does not support a separate workspace spend cap. An administrator should create a suitable ordinary API workspace when a project-level budget is needed.

Workspace management · Rate and spend limits

When the exercise is complete, clear the key from this session and exit the temporary Bash shell:

unset ANTHROPIC_API_KEY
exit

This ends the child shell’s temporary environment changes, while preserving the parent terminal’s original environment.

Download the complete examples below to review and use in your own practice directory. The code has passed syntax and offline workflow checks; no real model requests were made using a reader’s account.