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
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:
| Topic | What the docs say |
|---|---|
| Where requests run | In your organization: your rate limits, model access, retention and encryption apply |
| Data arrangements | The customer's zero data retention, BAAs and CMEK do not carry over |
| Regulated customers | Do not link customers who need HIPAA, FERPA or CMEK coverage for this usage |
/v1/messages | Supported; a customer-billed request cannot use billable code execution (400) |
/v1/chat/completions | Supported |
/v1/messages/count_tokens | Accepts and ignores billing_policy |
| Message Batches | Not 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).
The one-time link
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]:
| Item | Lifetime |
|---|---|
request_uri from the PAR endpoint | 10 minutes, single use |
| Authorization code | 5 minutes, single use |
| Access token | Up to 1 hour |
| Refresh token | Up 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:
{
"model": "claude-sonnet-5-5",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "Hello, Claude"}],
"billing_policy": {"type": "billing_policy", "bill_to": "user_profile"}
}| Header | Value |
|---|---|
anthropic-version | 2026-10-21 |
anthropic-beta | user-profiles-billing-2026-10-01 |
anthropic-user-profile-id | The 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.
| Error | Meaning | Retry? |
|---|---|---|
403 user_profile_not_billable | Anthropic cannot bill this customer, without saying why | No, except in the first 10 seconds of a new connection |
402 linked_organization_billing_unavailable | The customer's organization cannot be billed right now, for example it is suspended | No |
402 linked_organization_spend_limit_reached | Your app's spend cap or the organization's monthly limit is reached, or no eligible credit | No |
503 overloaded_error | Billing status could not be confirmed; nothing was served or billed | Yes, with backoff and retry-after |
400 user_profile_required | bill_to is user_profile but the profile header is missing | Fix 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:
- Confirm your customers pay Anthropic directly; marketplace-billed and subscription-only organizations cannot be billed.
- Keep regulated workloads that need HIPAA, FERPA or CMEK coverage on your own billing.
- Add a fallback path that resends refused requests with
bill_toset toself, if your pricing allows it. - 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].
- 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.