Claude Linked Billing: Power-User Guide to Setup, Spend Caps and Eligibility

Last updated: November 18, 2026

Claude Linked billing is a Claude Platform beta, launched November 17, 2026, that lets third-party apps bill Claude API usage to a customer’s own Claude organization instead of asking for an API key. The customer approves the app once, sets an optional monthly spend cap, and can unlink at any time. Only organizations that pay Anthropic directly qualify.

Contents

What Anthropic released on November 17

The Claude Platform release notes for November 17, 2026 say Anthropic launched Linked billing in beta with the user-profiles-billing-2026-10-01 beta header. Once a customer links its organization, the app sets billing_policy on each /v1/messages or /v1/chat/completions request to choose who pays.

In its announcement, Anthropic says the feature targets platforms such as coding agents and workflow automation tools. Customers can draw down an existing commitment or pay as they go. Launch platforms include Asana, Linear, Railway, Ramp and Warp.

For other recent Claude Platform changes, see our Claude text watermark guide.

Linked billing vs. sharing an API key

Anthropic compares the feature with the usual approach, where a customer pastes an API key into a third-party tool. A key works like a password, so the platform must protect it. The table summarizes the differences.

Area Shared API key Linked billing (beta)
What the app holds The customer’s API key A connection to a user profile; no customer key
Where requests run Under the customer’s own key The app’s organization, with the app’s rate limits and model access
Who pays The customer, for every call made with the key Chosen per request: the customer or the app
Customer controls Revoke or rotate the key Per-app monthly spend cap and one-click unlink in Console
Key storage Platform must store, encrypt and rotate keys No customer keys to store
Customer data settings Not applicable Customer ZDR, BAA, CMEK and IP allowlists do not apply
Eligible organizations Any API organization Only those billed directly by Anthropic

How customers link an app

The Claude Help Center article for customers lists the approval steps. Only a Console member with the Admin or Billing role can approve, and one approval covers the whole organization.

  1. In the app, click the button to link your Claude organization.
  2. Sign in to Claude and, if you belong to more than one organization, pick the one to link.
  3. Read how billing works, then set a monthly spend limit or select “Continue without a limit.” An app still in testing requires a limit of $50 or less.
  4. Review the approval screen, which shows the app’s name.
  5. Select “Link and authorize” to return to the app. Admin and Billing members usually get a confirmation email.

To unlink, open the Linked platforms page in the Console. New calls usually stop within about 10 seconds, and calls already running finish and are billed to you.

How developers add Linked billing

The Linked billing developer docs describe a one-time setup that needs the Admin role in the platform’s organization:

  1. Create an OAuth app on the OAuth apps page in the Console and select Bill and link to organizations.
  2. Set up client authentication with your own identity provider. Anthropic does not issue client secrets.
  3. Create a service account through Workload Identity Federation and select it as the app’s operator service account.
  4. Create one user profile per customer Claude organization, then send the customer through the hosted approval flow and save the connection.
  5. Publish the app. Unless your organization has invoiced billing, you verify your domain with a DNS TXT record and Anthropic reviews the app.

To bill a customer, add billing_policy with bill_to: "user_profile", the beta header and the customer’s profile ID. This example follows the docs:

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 "anthropic-user-profile-id: uprof_01HV9Z" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-5-5", "max_tokens": 1024,
       "messages": [{"role": "user", "content": "Hello, Claude"}],
       "billing_policy": {"type": "billing_policy", "bill_to": "user_profile"}}'

Use bill_to: "self", or leave out billing_policy, for requests the platform pays for. The operator credential can bill every linked customer by default, so check that the header names the right profile, or use per-connection OAuth tokens. Bill customers only for usage they direct.

For model choices and API changes, see our Claude Haiku 5.5 guide and our Claude Fable 5.2 guide.

Spend caps, credits and usage reports

Caps are optional, in whole US dollars, and set per app or as a default that applies to each app separately, according to the docs. A $0 cap refuses every customer-billed request. Caps count token costs and web search fees at list price before discounts, so the invoice can differ.

  • Can pay: purchased prepaid credit, monthly invoicing, billing corrections and credits written into an agreement.
  • Cannot pay: monthly API credits included with Max, Ultra and Team plans, product-specific sign-up credits, and credits from Anthropic’s partner, venture capital and startup programs.
  • Alerts: admins usually get emails at 80% and 100% of an app’s cap.

Platforms see each linked customer’s request count, token usage and models in Console or through the Usage and Cost Analytics API (beta). Console figures refresh about once an hour, so they are not suited to real-time cutoffs.

Errors to handle

When a request sets bill_to: "user_profile", Anthropic either bills the customer or refuses the request; it never bills the platform instead. The main cases:

  • 403 user_profile_not_billable: the customer cannot be billed; retry only within about 10 seconds of a new connection.
  • 402 linked_organization_spend_limit_reached: a cap or the organization’s monthly limit was reached, or no eligible credit remains. The response does not say which.
  • 400 user_profile_required: the profile ID header is missing.

In each refusal case, the platform can still serve the customer at its own cost by resending with bill_to: "self". A successful response does not say who was billed, so keep your own records.

Limits and caveats

  • Beta terms. Endpoints, parameters and behavior can change, and Anthropic says it might not suit production use.
  • Coverage gaps. Message Batches and Claude Managed Agents are not covered yet, and customer-billed requests cannot use billable code execution.
  • Ineligible customers. Bedrock, Vertex AI and Foundry users, subscription-only plans, and cloud marketplace billing cannot link, according to the platform help article.
  • Testing limits. A new app allows up to 10 test users, each with a cap of $50 or less, until it is published.

For a comparable routing and billing change on another platform, see our Hugging Face OpenRouter routing guide. Claude Code users can also read our Claude Code Projects guide.

Frequently asked questions

What is Claude Linked billing?

Linked billing is a Claude Platform beta, launched November 17, 2026, that lets a third-party app bill Claude API usage to a customer’s own Claude organization. No API key is shared.

Can I use my Claude Pro or Max subscription with Linked billing?

No. Anthropic says Claude subscription plans (Pro, Max, Ultra, Team and Enterprise) cannot be linked. The organization must pay Anthropic directly for API usage through prepaid credits or invoiced billing.

Who in my organization can approve a link?

A Claude Console member with the Admin or Billing role. The link belongs to the organization and stays active if the approver leaves.

How do spend caps work for linked apps?

On the Linked platforms page in the Claude Console, you can set a monthly cap in whole US dollars for each app. At the cap, the app’s customer-billed requests are refused until you raise it or the month resets on the 1st (UTC).

Do my zero data retention or HIPAA settings apply to linked requests?

No. Requests run in the app’s organization, so your IP allowlists, encryption keys, data retention settings, BAA and zero data retention do not apply.

Sources

Image: Anthropic announcement artwork for Linked billing on the Claude Platform, used for editorial purposes. Courtesy of Anthropic.

Related answers

Leave a Comment