How does Claude Linked billing let customers pay for your app's usage?

Claude Linked billing, in beta since November 17, 2026, bills a linked customer's own Claude organization for requests marked bill_to user_profile.

한국어로 읽기

Key takeaways

  • Claude Linked billing launched in beta on November 17, 2026.
  • Customers link their Claude organization to your app once through OAuth.
  • Each request sets billing_policy to bill the customer or yourself.
  • A customer request that cannot be billed fails with a 402 or 403.
  • Customers set monthly spend caps and can unlink in the Claude Console.
On this page
  1. What is Claude Linked billing?
  2. Who can use it?
  3. How does Linked billing work?
  4. The one-time link
  5. The per-request choice
  6. What happens when a customer cannot be billed?
  7. How do spend caps and unlinking work?
  8. What does this mean for teams running AI agents?
  9. What are the limits and open questions?

Claude Linked billing is a beta feature, launched November 17, 2026, that lets your customers pay for the Claude usage in your app through their own Claude organization [1]. A customer links their organization to your app once through OAuth. After that you set billing_policy on each /v1/messages or /v1/chat/completions request to choose who pays, and the customer can cap or cut off spending from the Claude Console.

What is Claude Linked billing?

Linked billing is a per-request choice of payer between you and a linked customer. The customer links their Claude Platform organization to your app once, and the API calls that link a connection [2]. On every request you decide whether the customer or you pays, and the customer can unlink at any time.

The key guarantee is in the failure case. If you mark a request for the customer and Anthropic cannot bill them, the API refuses the request; it never quietly bills you instead [2]. The release note introduces it with the beta header user-profiles-billing-2026-10-01 [1].

Both the feature and Claude Platform OAuth are a Beta Service: endpoints, parameters and behavior can change, and Anthropic says it might not be suitable for production use [2][3].

Who can use it?

Only customer organizations that pay Anthropic directly for API usage, through prepaid credits or invoiced billing, can be billed [1][2]. Organizations billed through the AWS, Google Cloud or Azure marketplaces, and organizations that only have a Claude subscription plan, are refused with 403 user_profile_not_billable. Promotional credits cannot pay either, including the monthly credits of the Max, Ultra and Team plans and credits from partner, VC and startup programs.

The other limits matter as much as the payer:

TopicWhat the docs say
Where requests runIn your organization: your rate limits, model access, retention and encryption apply
Data arrangementsThe customer's zero data retention, BAAs and CMEK do not carry over
Regulated customersDo not link customers who need HIPAA, FERPA or CMEK coverage for this usage
/v1/messagesSupported; a customer-billed request cannot use billable code execution (400)
/v1/chat/completionsSupported
/v1/messages/count_tokensAccepts and ignores billing_policy
Message BatchesNot supported; a customer-billed batch request returns errored and nobody is charged

All of these rows come from the Linked billing guide [2].

How does Linked billing work?

Linked billing works in two phases: a one-time OAuth link per customer, then a billing decision on every request. The figure shows both, simplified (the user's browser carries the redirect between your app and Anthropic).

Sequence diagram: your back end starts a link, the customer admin sets a spend cap and approves, you get a connection ID, then requests with bill_to user_profile are billed to the customer or refused with 402 or 403.
Linking a customer once, then choosing the payer on each request, simplified (source [2]).

Setup starts in the Claude Console. An Admin creates an OAuth app with a redirect URI and the option Bill and link to organizations [2]. Anthropic issues no client secrets: your back end authenticates with private_key_jwt-style client assertions from a registered identity provider. You also need an operator service account, set up through Workload Identity Federation, and each service account can operate only one app.

For each customer you create a user profile, then push an authorization request (PAR) to auth.claude.com with that profile's ID, the scope billing:attribution (plus offline_access if you want a refresh token), connection_type set to organization_shared and a PKCE challenge [2]. The user who approves must hold the Admin or Billing role in their organization. On Anthropic's pages they pick an organization, read how billing works, set a monthly spend limit for your app and click Link and authorize.

Your callback then exchanges the code and receives a connection_id and an access token that bills only that customer. Connections are one-to-one within an app: one Claude organization links to one of your user profiles, so several teams in the same customer organization should share one profile [2].

The OAuth lifetimes are short, so plan for them [3]:

ItemLifetime
request_uri from the PAR endpoint10 minutes, single use
Authorization code5 minutes, single use
Access tokenUp to 1 hour
Refresh tokenUp to 1 year from the code exchange; a refresh does not extend it

The per-request choice

To bill the customer, send the anthropic-user-profile-id header, the beta header, and a billing_policy with bill_to set to user_profile [2]. To pay yourself, omit billing_policy or send bill_to set to self. The request body for a customer-billed call looks like this:

JSON
{
  "model": "claude-sonnet-5-5",
  "max_tokens": 1024,
  "messages": [{"role": "user", "content": "Hello, Claude"}],
  "billing_policy": {"type": "billing_policy", "bill_to": "user_profile"}
}
HeaderValue
anthropic-version2026-10-21
anthropic-betauser-profiles-billing-2026-10-01
anthropic-user-profile-idThe customer's user profile ID

The guide asks you to use user_profile only for usage the customer directs, not for your own testing or other work [2].

That warning comes straight from the guide [2]. The narrower option is to call Claude with each connection's own access token, which can bill only its own customer and refuses requests that name another profile or set bill_to to self. A beta setting can also turn off operator-only authentication, so that customer billing requires connection tokens.

What happens when a customer cannot be billed?

A customer-billed request that Anthropic cannot charge fails with a specific error, and you can resend it with bill_to set to self to serve the customer at your own cost [2]. On /v1/messages the code is in error.details.error_code; /v1/chat/completions returns the same status and message in OpenAI format without the code.

ErrorMeaningRetry?
403 user_profile_not_billableAnthropic cannot bill this customer, without saying whyNo, except in the first 10 seconds of a new connection
402 linked_organization_billing_unavailableThe customer's organization cannot be billed right now, for example it is suspendedNo
402 linked_organization_spend_limit_reachedYour app's spend cap or the organization's monthly limit is reached, or no eligible creditNo
503 overloaded_errorBilling status could not be confirmed; nothing was served or billedYes, with backoff and retry-after
400 user_profile_requiredbill_to is user_profile but the profile header is missingFix the request

A successful response does not say who was billed, so the guide tells you to keep your own record of which requests you sent with bill_to set to user_profile [2]. In the cost endpoint of the Usage and Cost Analytics API, customer-paid requests add 0 to amount and their list price to list_amount.

How do spend caps and unlinking work?

The customer controls the money side from the Linked platforms page in the Claude Console, and you cannot see their cap [2]. A member with the Admin or Billing role can set a monthly cap in whole US dollars for your app, set a default cap for all linked apps, or remove a cap. The smallest cap is $0, which refuses every request you bill to that customer, and the cap counts token costs and web search fees at list prices before any negotiated discount.

When the cap is reached, customer-billed requests get a 402 until 00:00 UTC on the first day of the next month or until the customer raises or removes the cap; a change can take about a minute to apply [2]. While your app is in testing, in review or not approved, a cap is required and can be at most $50.

Customers can unlink at any time, and Anthropic sends you no webhook and no email when they do [2]. To check a customer, call GET /v1/user_profiles/{id} with your app's client ID in oauth_app_id and the user-profiles-search-2026-08-30 beta header; connection_status.type returns connected, disconnected or not_connected.

What does this mean for teams running AI agents?

For teams that ship agents to other companies, Linked billing moves model spend onto the customer's own Anthropic account without you reselling tokens, while you keep your own rate limits and model access [2]. The customer's administrators get a cap and an off switch they control, which is often what a finance team asks for before it lets an outside agent run on its budget.

If you plan to try it, check these points first:

  1. Confirm your customers pay Anthropic directly; marketplace-billed and subscription-only organizations cannot be billed.
  2. Keep regulated workloads that need HIPAA, FERPA or CMEK coverage on your own billing.
  3. Add a fallback path that resends refused requests with bill_to set to self, if your pricing allows it.
  4. Store refresh tokens as soon as each refresh returns them: they rotate on every use, and reusing one more than 30 seconds after its first use ends the connection [2].
  5. Poll link status, since unlinking sends you no notice.

What are the limits and open questions?

The biggest limit is visibility. Error responses do not say why a customer cannot be billed, you cannot read a customer's cap or remaining budget, and Anthropic does not tell you which organization a connection belongs to [2]. The guide suggests describing a finished link to your user as "linked", not "billing active".

Distribution is also gated. Until your app is published, only listed test users can link it; publishing requires a DNS TXT proof of your homepage domain unless your organization has invoiced billing, and Anthropic then reviews the app [2]. Batches and billable code execution cannot be billed to customers yet, and the docs do not say when the beta will end or whether that will change.

Frequently asked questions

Which customers can pay through Claude Linked billing?

Only organizations that pay Anthropic directly for API usage, through prepaid credits or invoiced billing. Organizations billed through the AWS, Google Cloud or Azure marketplaces, or with only a Claude subscription plan, are refused with 403 user_profile_not_billable, and promotional credits cannot pay.

What happens if a customer's spend cap is reached?

Requests billed to that customer are refused with 402 linked_organization_spend_limit_reached until 00:00 UTC on the first day of the next month, or until the customer raises or removes the cap. You can still serve the customer at your own cost by resending with bill_to set to self.

Does a customer's zero data retention or BAA apply to linked requests?

No. Linked requests run in your organization, so your rate limits, model access, retention and encryption apply. The customer's zero data retention, BAAs and CMEK do not carry over, and Anthropic says not to link customers who need HIPAA, FERPA or CMEK coverage for this usage.

Will I be notified when a customer unlinks my app?

No. Anthropic sends you no webhook and no email when a customer unlinks. Check status with GET /v1/user_profiles/{id} and the user-profiles-search-2026-08-30 beta header, which returns connected, disconnected or not_connected.

Can Message Batches be billed to a linked customer?

No. A batch request with bill_to set to user_profile returns errored with invalid_request_error, and neither you nor the customer is charged.

Sources

  1. Claude Platform release notes — Anthropic, accessed
  2. Linked billing — Anthropic, accessed
  3. OAuth reference — Anthropic, accessed