Anthropic Linked Billing: Route App Costs to Customer Organizations

Learn how Anthropic Linked billing lets customers pay for Claude API usage in your application via OAuth and the user-profiles-billing-2026-10-01 header.

By ailog · Published Nov 21, 2026 · 7 min read · How we work
In short
  • Anthropic launched Linked billing in beta on 2026-11-17 using the user-profiles-billing-2026-10-01 beta header.
  • Developers can route Claude API token expenses to end-customer Claude organizations while running requests within their own developer tenant.
  • Supported endpoints include /v1/messages and /v1/chat/completions, with /v1/messages/count_tokens ignoring the policy for budgeting pre-checks.
  • Customers billed via cloud marketplaces (AWS, Google Cloud, Azure) or consumer subscription tiers cannot be linked and fail with a 403 error.
  • Requests marked for the customer cannot run billable code execution tools or message batches, failing instead of falling back to developer billing.

Understanding Linked Billing and How It Shifts API Costs

Software vendors integrating generative models traditionally absorb inference charges and pass them down through recurring software tiers, seat add-ons, or custom invoices. On 2026-11-17, Anthropic introduced Linked billing in public beta under the user-profiles-billing-2026-10-01 beta header. This capability allows developers building on the Claude Platform to let external customer organizations pay directly for API tokens consumed inside third-party tools.

Under this architecture, your software authenticates customer organizations via standard OAuth workflows. Once established, each connection pairs an internal customer profile with an external Claude workspace. Rather than paying the raw model costs—such as $2 per 1M input tokens and $10 per 1M output tokens for Claude Sonnet 5.5, or $4 input and $20 output for Claude Opus 5.5—the platform charges those sums straight to the balance of the customer. You can evaluate model rates and plan budgets via the /tools/llm-api-pricing/ tracker.

A crucial structural detail is that requests still execute within your developer account. This architecture preserves your organization-level configurations: your custom rate limit ceilings, default model access rules, operational service tiers, and encryption keys continue to control traffic. The external customer simply assumes the financial liability for designated calls without receiving access to your private credentials.

Account Eligibility, Credit Types, and Compliance Boundaries

Linked billing functions only for specific account setups. The external customer organization must pay Anthropic directly for its usage. This eligibility covers accounts holding prepaid console credits and organizations configured for direct invoiced payment. Third-party cloud marketplace channels—including billing through AWS, Google Cloud, or Azure—are strictly ineligible. Similarly, users holding only standard Claude subscription plans cannot be billed for API usage through this mechanism. If an app attempts to charge an ineligible organization, the Claude API rejects the request with a 403 user_profile_not_billable status code.

Specific payment instruments also face restrictions on linked connections. Credit purchased directly inside the Claude Console or accumulated through invoiced terms is valid. However, promotional allowances cannot cover these requests. This exclusion removes monthly API credits provided under Claude Max, Ultra, and Team tiers, alongside grant allotments from startup, VC, and partner channels. If the customer balance contains insufficient eligible funds or exceeds an account threshold, the engine returns a 402 error.

Security and compliance teams must evaluate data governance carefully before deployment. Because inference runs in the developer tenant, the customer’s organizational data contracts do not apply to the generated traffic. This exclusion nullifies customer-specific zero data retention (ZDR) scopes, customer-managed encryption keys (CMEK), and Business Associate Agreements (BAA). Organizations requiring specialized protections under HIPAA or FERPA should avoid linking accounts under this beta service. Further governance patterns can be reviewed in /posts/api-data-retention-and-training-policies-anthropic-openai-google/.

Infrastructure Setup: OAuth Apps and Workload Identity Federation

Configuring Linked billing requires administrative privileges inside your Claude Console tenant. The setup does not rely on static API tokens or conventional client secrets. Instead, authentication utilizes cryptographic tokens governed by RFC 7523 private_key_jwt assertions and federated credentials. Detailed security foundations for this mechanism are documented in /posts/anthropic-ip-allowlisting-and-session-revocation-setup-guide/.

  • Step 1: Register the OAuth Application. Under the OAuth apps dashboard, create a new record, designate your callback redirect URI, and assign permissions for organization linking and billing. Note the generated client ID, which is public and referenced during authentication exchanges.
  • Step 2: Establish Client Authentication. Connect your identity issuer (such as Kubernetes, AWS, or Google Cloud). Configure subject patterns and claim conditions. Your back end issues JWT assertions targeting the exact expected audience value displayed in the console.
  • Step 3: Provision an Operator Service Account. Generate a dedicated service account within your Claude organization. Bind this non-human account as the exclusive operator service account for your registered OAuth app, ensuring only authorized services can attribute calls to customer profiles.

New applications default to test status, displaying ‘Test users only’ in console settings until formally moved to production status (‘Any Claude user’). Each registered OAuth application maintains its own isolated connections; test links do not carry over to live applications.

Implementing Connection Flows and User Profile Records

Every linked organization requires an anchor inside your system called a user profile. Connections maintain a strict one-to-one relationship within an application: a single customer Claude organization connects to exactly one user profile, and that user profile cannot link to multiple Claude organizations. If multiple teams inside a client company share one Claude organization, they must map to a single profile. Conversely, independent organizations require distinct profiles. Attempting to bind a second profile to an active connection produces a user_profile_already_linked error.

Profiles are provisioned programmatically using the /v1/user_profiles endpoint. Applications reselling platform access should pass an access type of passthrough, whereas native software integrations omit the field to create standard application profiles. Because each creation call issues a distinct identifier (such as uprof_01HV9Z), profiles should be generated once per tenant and stored in your database.

curl https://api.anthropic.com/v1/user_profiles \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "anthropic-version: 2026-10-21" \
  -H "content-type: application/json" \
  -d '{
    "name": "Example Customer Inc.",
    "external_user_details": {"reference_id": "your-customer-id-123"}
  }'

After establishing the profile, your application initiates a Pushed Authorization Request (PAR) using the customer profile ID, receives a request URI, and directs the client administrator (holding Admin or Billing roles) to complete consent. For tracking individual actors under a shared enterprise profile, developers can supply an opaque string in metadata.user_id without transmitting plain user identities.

Sending Inference Requests with the billing_policy Field

Billing routing is determined per request. Applications must include the user-profiles-billing-2026-10-01 beta header alongside the operational anthropic-version: 2026-10-21 header. Routing behavior is dictated by the billing_policy configuration. When routing expenses to the external client, designate bill_to: "user_profile" alongside the customer’s profile identifier. When absorbing costs internally, supply bill_to: "self" or omit the policy entirely.

curl https://api.anthropic.com/v1/messages \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "anthropic-version: 2026-10-21" \
  -H "anthropic-beta: user-profiles-billing-2026-10-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5.5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Summarize system operations."}],
    "billing_policy": {
      "bill_to": "user_profile",
      "user_profile_id": "uprof_01HV9Z"
    }
  }'

The platform strictly enforces that a customer-routed request will fail immediately rather than silently fall back to billing the developer. If an organization link is severed, revoked by the client, or lacks available credit, the request aborts cleanly, protecting developers from surprise liabilities.

Endpoint Scope, Feature Constraints, and Provider Comparisons

Linked billing does not apply uniformly across all Claude endpoints. It is active on /v1/messages and /v1/chat/completions. When verifying prompt sizes via /v1/messages/count_tokens, the API accepts the payload structure and ignores billing_policy, allowing systems to perform token estimations using identical bodies without throwing schema errors. To estimate call expenses across workloads, explore /tools/llm-api-cost-calculator/.

Two major feature limitations exist in the beta release: billable code execution and batch processing. Any request carrying bill_to: "user_profile" that triggers billable code execution tools receives an HTTP 400 rejection; developers must route code execution workloads through bill_to: "self". Similarly, the Message Batches endpoint (/v1/messages/batches) does not permit customer billing. If a batched task specifies customer billing, that individual record fails with an invalid_request_error while the rest of the batch runs under developer billing, as detailed in /posts/batch-processing-apis-step-by-step-claude-openai-and-gemini/.

Capability / Parameter Anthropic Linked Billing Standard API Direct Billing
Beta Header Required user-profiles-billing-2026-10-01 None
Billing Mechanism OAuth connection to customer organization Developer API key or service account
Supported Endpoints /v1/messages, /v1/chat/completions All endpoints including /v1/messages/batches
Code Execution Support Blocked on customer requests (HTTP 400) Supported (billed to account owner)
Batch Processing Unsupported for customer billing Supported (50% discount on batches)
Default Failure Policy Refuses call; developer is never billed Refuses call on exhausted balance

Deployment Checklist for Linked Billing Integrations

Before introducing user-profile billing into staging or production environments, verify your architecture against these core technical constraints:

  • Confirm client payment source: Verify that the customer organization pays Anthropic directly through prepaid console credit or invoice terms, rather than marketplace agreements or consumer tiers.
  • Verify compliance terms: Ensure neither party relies on BAA, HIPAA, FERPA, or CMEK provisions for requests billed to the customer.
  • Check authorization roles: Ensure connecting users possess either the Admin or Billing permission set within their Claude workspace.
  • Inspect token headers: Verify that inference payloads include anthropic-beta: user-profiles-billing-2026-10-01 and an active operator service account token.
  • Enforce routing policies: Ensure calls involving batch endpoints or code execution tools set bill_to to self or omit billing_policy entirely.
  • Handle status codes: Implement logic to handle 400 (unsupported tools), 402 (spend limit or balance exhaustion), and 403 (ineligible organization) responses.
Sources
  1. Anthropic Claude Platform release notes — 2026-11-17
  2. Linked billing

Related