top of page

Claude API linked billing beta shifts app usage costs to customers

2 hours ago
9 min read
Cover with the Claude logo and the title Claude API linked billing beta shifts app usage costs to customers. Data Studios original cover

Anthropic has opened a beta of linked billing on the Claude Platform, a mechanism that lets a developer's customers pay for the Claude usage their app generates through their own Claude organization. The feature appeared in the Claude Platform release notes on November 17, 2026, and it works on the two main inference endpoints, /v1/messages and the OpenAI-compatible /v1/chat/completions. Requests that use it must carry the beta header user-profiles-billing-2026-10-01, and Anthropic describes the whole service as a beta whose endpoints, parameters and behavior can still change.


The model is simple to state. A customer links its Claude organization to a developer's app once, through an OAuth approval screen hosted on auth.claude.com, and that link creates a connection with an ocon_ identifier. From then on, the developer decides request by request who pays: the customer, by setting bill_to to "user_profile" inside a new billing_policy body field, or the developer, by setting bill_to to "self" or leaving the field out. When a request marked for the customer cannot be charged to that customer, the API refuses it and never bills the developer in its place.


For the customer, the price is the public list price of each request. For the developer, the feature removes one of the hardest parts of selling an AI product to businesses, which is carrying the token bill of every client and reselling it with a margin and a usage policy. The customer keeps control through a monthly spend cap per app, set in whole US dollars, and can unlink the app at any time from the Claude Console.


··········


HOW CLAUDE PLATFORM LINKED BILLING WORKS PER REQUEST.


Each request that should be charged to a customer needs three elements. The first is the header anthropic-user-profile-id, set to the user profile identifier (prefix uprof_) that holds the customer's connection. The second is the beta header user-profiles-billing-2026-10-01, which Anthropic requires whenever billing_policy is sent. The third is the body field billing_policy, with type set to "billing_policy" and bill_to set to "user_profile".


The same app can mix both modes freely. A developer could charge a customer for the long research tasks that customer launches while paying itself for onboarding, previews or a free tier. Anthropic's documentation asks developers to use bill_to: "user_profile" only for usage the customer directs, and to keep their own testing and work done for other customers on their own account; the documentation also states that the API has no way to verify this, so the rule rests on the developer's own controls and contracts.


Requests always run inside the developer's organization. The developer's rate limits, model access, service tier, data retention settings and encryption keys apply, whoever pays. A customer's own contractual arrangements do not travel with the bill: zero data retention, a business associate agreement or customer-managed encryption keys held by the customer's organization do not cover usage that runs through someone else's app. Anthropic tells developers plainly not to link customers who need HIPAA, FERPA or CMEK coverage for that usage.


A successful response does not say who was billed. Developers therefore need to keep their own record of which requests carried bill_to: "user_profile", which is also the basis for any invoice reconciliation with the customer later.


··········


WHO CAN USE CLAUDE LINKED BILLING AND WHICH ENDPOINTS ARE EXCLUDED.


Eligibility depends on how the customer's organization pays Anthropic. Organizations that pay Anthropic directly for API usage, with prepaid credits bought in the Claude Console or with invoiced billing, can be linked. Organizations billed through the AWS, Google Cloud or Azure marketplaces cannot, and neither can organizations that hold only a Claude subscription plan; both receive a 403 user_profile_not_billable error. The monthly API credits included in Max, Ultra and Team plans, and credits from Anthropic's partner, venture capital and startup programs, cannot pay for linked requests either.


........


Element

Status in the linked billing beta

/v1/messages

Supported; billable code execution not allowed with bill_to "user_profile"

/v1/chat/completions

Supported

/v1/messages/count_tokens

Accepts and ignores billing_policy

/v1/messages/batches

Not supported for customer billing; item returns errored

Direct API customers (prepaid or invoiced)

Eligible

AWS, Google Cloud, Azure marketplace billing

Not eligible (403)

Subscription-only organizations

Not eligible (403)

Max, Ultra, Team API credits; partner and startup credits

Cannot pay


........


The exclusion of the Message Batches API has a direct cost consequence. Batch processing is priced at half the standard rate for input and output on the Claude Platform, so workloads that a developer runs in batch to save money cannot be passed to customers through this mechanism. A batch item sent with bill_to: "user_profile" comes back as errored with invalid_request_error, and neither party is charged. Billable code execution is also blocked for customer-billed requests on /v1/messages, with a 400 error.


··········


SETTING UP A CLAUDE OAUTH APP AND LINKING A CUSTOMER ORGANIZATION.


The one-time setup happens in the Claude Console. A developer creates an OAuth app on the OAuth apps page with the option "Bill and link to organizations", then configures client authentication. Anthropic issues no client secrets for these apps: the developer's back end proves its identity with a private_key_jwt-style client assertion under RFC 7523, issued by the developer's own identity provider through Workload Identity Federation. The last setup step is a service account for the back end, assigned as the app's operator service account.


Linking a customer follows a standard OAuth authorization code flow with pushed authorization requests. The developer first creates a user profile for the customer's organization and stores its identifier, because every create call produces a new profile. It then pushes an authorization request to https://auth.claude.com/v1/oauth/par with the scope billing:attribution (or billing:attribution offline_access to receive refresh tokens), the connection type organization_shared, a PKCE challenge with method S256 and the client assertion. The returned request_uri is valid for 600 seconds.


The customer's administrator is then redirected to auth.claude.com, signs in, picks an organization if there are several, sets a monthly spend limit and clicks "Link and authorize". Only users with the Admin or Billing role can approve. The developer exchanges the one-time code, valid for five minutes, at the token endpoint and receives a connection_id, an access token and, when requested, a refresh token. Anthropic returns these values once, so they must be stored immediately.


Connections are strictly one-to-one: a customer organization links to a single profile of a given app, and a profile links to a single organization. The connection belongs to the organization, so it survives if the employee who approved it leaves.


By default, the operator service account can bill any linked customer by sending the profile header and bill_to. Developers who want tighter isolation can switch to connection-bound tokens, which expire within one hour, are sent as Bearer tokens and can bill only their own customer. Refresh tokens last at most one year and rotate on every refresh. Setting disable_operator_only_auth to true blocks the tokenless mode entirely.


··········


SPEND CAPS, UNLINKING AND ERROR CODES IN CLAUDE LINKED BILLING.


Customers set a monthly spend cap for each linked app in whole US dollars, and they can define a default cap for apps that have none. A cap of $0 refuses every request billed to that customer. Caps count token costs and web search fees at list price, before any negotiated discount, and the organization's own monthly spend limit keeps applying alongside them. While a developer's app is in testing, in review or not yet approved, Anthropic imposes a cap of $50 or less, and the approval screen pre-fills $50. Developers cannot read a customer's cap or how much of it has been consumed.


When a cap is reached, requests fail until 00:00 UTC on the first day of the following month, or until the customer changes the cap, which can take about a minute to apply. Unlinking is equally one-sided: a customer can remove the app from the Linked platforms page in the Console at any time, and Anthropic sends the developer no webhook or email. Developers can check status with GET /v1/user_profiles/{id}, which returns connected, disconnected or not_connected.


........


HTTP status

Error code

Cause

What the app can do

403

user_profile_not_billable

Ineligible org, no active connection or wrong credential

Retry only within 10 seconds of a new link; otherwise bill "self"

402

linked_organization_spend_limit_reached

App cap, org monthly limit or no payable credit

Do not retry; resend with bill_to "self" to keep serving

402

linked_organization_billing_unavailable

Org suspended or credit ran out mid-reply

Do not retry

503

overloaded_error

Billing status could not be confirmed

Retry with backoff and retry-after

400

user_profile_required

Profile header missing

Fix the request


........


The 402 and 403 cases need a product decision before launch. An app can stop and tell the customer to raise the cap or relink, or it can absorb the cost by resending the request with bill_to: "self". Since the developer gets no notification of a cap change or an unlink, the first signal will often be a failed request in production.


··········


WHAT A CUSTOMER WOULD PAY: A CLAUDE SONNET 5.5 COST EXAMPLE.


Customer-billed requests are charged at the list prices on Anthropic's pricing page. As listed on the official Claude Platform pricing page on November 18, 2026, Claude Sonnet 5.5 costs $2.00 per 1M input tokens, $0.10 per 1M cache-hit tokens and $10.00 per 1M output tokens; Claude Opus 5.5 costs $4.00, $0.20 and $20.00; Claude Haiku 5.5, for prompts up to 100,000 tokens, costs $0.10, $0.01 and $0.50. Web search adds $10 per 1,000 searches.


Consider a team of 20 people at a customer company using an internal assistant built on Claude. Each person sends 40 requests per working day, over 22 working days, which gives 17,600 requests a month. Each request carries 2,000 new input tokens, reuses a 4,000-token cached system prompt and returns 800 output tokens. Cache writes are left out of the calculation, on the assumption that the shared prefix is already cached for most requests.


........


Model (list price)

Cost per request

Monthly cost, 17,600 requests

Requests covered by a $50 cap

Claude Haiku 5.5

$0.00064

$11.26

78,125

Claude Sonnet 5.5

$0.0124

$218.24

4,032

Claude Opus 5.5

$0.0248

$436.48

2,016


........


On Sonnet 5.5, the per-request figure comes from $0.004 of new input, $0.0004 of cached input and $0.008 of output. If one request in four also triggered a web search, the 4,400 searches would add $44 a month at list price, and that amount counts against the customer's cap as well. The $50 limit imposed on apps that are still in review therefore covers about two working days of this team's usage on Sonnet 5.5, or roughly one day on Opus 5.5, which sizes it as a test allowance.


··········


WHAT CHANGES FOR DEVELOPERS SELLING APPS BUILT ON CLAUDE.


Until now, a company selling a Claude-based product to business clients paid Anthropic for all inference and recovered the cost through its own pricing, often with usage tiers or overage fees. Linked billing allows a different commercial structure, closer to a "bring your own Claude account" model: the developer charges for the software, and the customer pays Anthropic directly for tokens, under a cap the customer controls. For developers, the benefits are reduced credit risk and no need to forecast every client's token volume. For customers, the main advantage is that AI spending stays on their existing Anthropic invoice, with a hard monthly ceiling per vendor.


The constraints are just as concrete. Customers must be direct API customers of Anthropic, which leaves out companies that buy Claude through AWS Bedrock, Google Cloud or Azure, and companies that only hold Claude subscriptions. Batch discounts cannot be passed through. Regulated customers who rely on their own ZDR, BAA or CMEK terms should not be linked. Developers also lose visibility: they cannot see a customer's cap, and Anthropic's analytics, which show customer-paid usage with an amount of 0 and a positive list_amount when grouped by user_profile_id, are not real time and are not meant for enforcing limits.


Readers comparing this with consumer subscriptions should keep the two systems apart: linked billing concerns API credit and invoices, while the Pro, Max and Team plans have separate usage rules described in our guide to Claude pricing and plan limits. The model prices, context windows and rate limits that still govern every linked request are covered in our overview of Claude API models, pricing and rate limits, and the Usage and Cost Analytics API beta is the tool Anthropic points to for per-profile reporting.


··········


CLAUDE LINKED BILLING BETA: CONFIRMED FACTS AND OPEN QUESTIONS.


The documented part is detailed. Linked billing has been live in beta since November 17, 2026, on /v1/messages and /v1/chat/completions, behind the user-profiles-billing-2026-10-01 header; customers pay list price; caps are monthly, per app, in whole dollars, with a $50 ceiling while an app awaits approval; batches, billable code execution, marketplace-billed organizations and subscription-only organizations are excluded; and the API refuses customer-billed requests it cannot charge and never moves them onto the developer's bill.


Several points remain undocumented. Anthropic has not published how long the beta will last, what the app review process involves or how long approval takes, whether marketplace-billed organizations will become eligible, or whether negotiated customer discounts will ever apply to linked usage, given that caps and analytics are calculated at list price. The pages also give no separate customer-level rate limits, which means a developer's own organization limits must absorb the traffic of every linked customer. For developers, the decision to adopt it in its current form depends mostly on whether their business clients pay Anthropic directly and whether their workloads can live without batch pricing.


··········


FOLLOW US FOR MORE.


·····


DATA STUDIOS


·····


datastudios.org


bottom of page