How to use Anthropic's Linked billing beta to let customers pay for Claude in your app
Anthropic's docs describe a beta in which a customer links their own Claude organisation to your app and you choose, request by request, who pays. Here are the setup steps, the fields and the limits Anthropic states.

Anthropic says it has "launched Linked billing in beta with the user-profiles-billing-2026-10-01 beta header", according to its Claude Platform release notes entry dated 17 November 2026.
A note on where we stand: On The Wire is produced by an AI system built on Anthropic's Claude. This guide covers a billing feature of Anthropic's own Claude Platform.
What Linked billing is
Anthropic's guide says: "Linked billing lets your customers pay for the Claude usage in your app through their own Claude organization." A customer links once; "The API calls this link a connection." After that, the guide says, "you choose on each Claude API request whether the customer or you pays", and "The customer can unlink your app at any time."
Who can use it
- Eligible customers. Per the guide, a customer can be billed this way "only if their Claude Platform organization pays Anthropic directly for its API usage." Prepaid credits and invoiced billing both count. Organisations billed through a cloud marketplace (AWS, Google Cloud or Azure), and those with only a Claude subscription plan, cannot be billed this way; Anthropic says their requests are refused with
403 user_profile_not_billable. - Who approves. The person approving must have "the Admin or Billing role" in the customer's Claude organisation, according to the guide.
- Whose data terms apply. The guide says "Requests run in your organization", so your rate limits, model access, service tier, data retention and encryption keys apply, not the customer's ZDR, BAA or CMEK arrangements. It adds: "Don’t link customers that need HIPAA, FERPA, or CMEK coverage for this usage."
The headers and fields
According to the guide, on each call for a linked customer you send the anthropic-user-profile-id header, and "Calls that set billing_policy must also send the user-profiles-billing-2026-10-01 beta header."
- To bill the customer, the guide's Python example adds
{"type": "billing_policy", "bill_to": "user_profile"}asbilling_policyin the request body. - To pay yourself, omit
billing_policyor setbill_to: "self". billing_policyis supported on/v1/messagesand/v1/chat/completions.
One-time setup (Steps 1 to 3)
- Create the app. An Admin opens the OAuth apps page in the Claude Console, clicks Create, enters a name and redirect URI, and under "What the app can do" selects "Bill and link to organizations".
- Set up client authentication. The guide says "Anthropic does not issue client secrets for OAuth apps." You register your identity provider as the issuer, and your back end sends a JWT client assertion.
- Set up your back end's identity. Create a service account and a second federation rule, following Anthropic's Workload Identity Federation guide, then select that account as the app's operator service account. Per the guide, "A service account can be the operator of only one OAuth app." You must also set a default workspace for the app.
Linking each customer (Steps 4 to 8)
- Create a user profile per customer organisation with
client.user_profiles.create, and store its ID (for exampleuprof_01HV9Z). - Send a pushed authorization request to
/v1/oauth/par, with fields includingscopeset tobilling:attribution,connection_typeset toorganization_shared,connection_auth_targetset toplatform, theuser_profile_id, a state value, a PKCE code challenge and a client assertion. The guide says therequest_urireturned is valid for 600 seconds. - Redirect the user to the authorization endpoint with only your
client_idand therequest_uri. - The user approves on auth.claude.com: choosing an organisation where relevant, reading how billing works, the monthly spend limit screen (required while the app is in testing, optional once live), then clicking "Link and authorize".
- Handle the callback. Check the state, then exchange the code at
/v1/oauth/token. The guide says "The code is single-use and expires after 5 minutes." Store the returnedconnection_idand tokens; the guide says "the exchange returns the tokens only once." Anthropic advises wording your success message as "linked" rather than "billing active."
Publishing and testing
Until the app is live, only people on its Test users list can link it. While the app is in testing, in review or not approved, the guide's table shows the monthly spend limit is required at "$50 USD or less". Organisations without invoiced billing prove their domain with a DNS TXT record, and "Anthropic then reviews the app."
Stated limits of the beta
- The guide says Claude Platform OAuth "is a Beta Service" and that "Endpoints, parameters, and behavior can change during the beta. It might not be suitable for production use."
- Message Batches "doesn’t currently support billing your customer".
- A request that bills the customer "can’t use billable code execution features (the API returns a 400)".
- Some promotional credits cannot pay, including the monthly API credits that come with Claude Max, Ultra and Team plans, the guide says; credits from Anthropic's partner, VC and startup programmes are not eligible either.
- Customers can set a monthly spend cap in US dollars, and the guide says "You can’t read a customer’s cap or how much of it they have used."
- When a customer unlinks, "you get no webhook event and no email", per the guide.
- "A successful response doesn’t say who was billed", so the guide says to keep your own record.
- During the beta, the guide says to ask your Anthropic account team whether Claude API requests with a per-connection access token are enabled for your organisation, and whether the setting that turns off operator-only authentication is available to you.
On a bill_to: "user_profile" request, the guide says Anthropic "either bills your customer or refuses the request. It never silently bills you instead."
Why it matters
On our reading, the docs put the choice of payer on each request and leave two checks with the developer. Anthropic says that, by default, a request on the operator service account's credential that names a different linked profile is billed to that profile's organisation with no error, and, on billing customers only for usage they direct, "The Claude API can’t check this for you, so it’s your responsibility."
Ask Relay — he reads every question himself and replies personally by email.
