Claude linked billing: billing_policy lets the customer pay, but the request still runs under your organization
One misread 403 can move all tenants onto your bill, while a wrong header charges somebody else. Where those failures hide, and what to log first.
Contents
Claude linked billing, which Anthropic launched in beta on November 17, 2026, lets a customer link their Claude organization to your app and pay for the Claude usage they cause there. Only the charge moves: the request still runs in your organization, under your rate limits, your model access and your retention terms. The payer guarantee is also easier to lose than it looks. Anthropic refuses a customer-billed request rather than charge you for it, and the docs then note that you can resend it with bill_to: "self". Put that resend in a generic fallback and one misconfigured credential moves every customer onto your invoice, with no error anywhere.
I haven’t run the real flow, which needs a registered OAuth app, workload identity federation and a second eligible organization. Protocol details below come from Anthropic’s docs as of November 19. The error handler is code I did run, with Python SDK 2.10.0 against a local stub returning the documented errors, so it shows how my code behaves and says nothing about Anthropic’s servers. The recommendations are my reading.
What does Claude linked billing move to the customer?
The charge, and almost nothing else. Anthropic bills the customer’s organization for the requests you mark, and the customer can set a monthly spend cap for your app or unlink it. How the request is served stays with you:
| Whose it is on a customer-billed request | |
|---|---|
| The charge | the customer’s organization |
| Optional monthly spend cap for your app | the customer’s, and you can’t read it |
| Rate limits, model access, service tier | yours |
| Data retention and encryption keys | yours |
| The customer’s ZDR, BAA, CMEK | don’t apply |
The last row is the one to put in front of your sales and security people. A customer with zero data retention on their own organization may assume it follows the invoice. It doesn’t, and the docs say not to link customers that need HIPAA, FERPA or CMEK coverage for this usage.
Which organizations can use Claude linked billing?
Both sides have to pay Anthropic directly. Your own organization does, or customer-billed requests fail with a 403 that carries no error code. The customer’s organization must pay for API usage by prepaid credits or invoice. Organizations billed through AWS, Google Cloud or Azure marketplaces are out, and so are those with only a Claude subscription plan. Their requests get 403 user_profile_not_billable.
Credit type matters too. Credit bought in the Console can pay. The monthly API credits that come with Max, Ultra and Team plans can’t, so the balance you may have claimed with one of those plans won’t cover it, and neither will credits from Anthropic’s partner, VC and startup programs.
A link can complete with none of this in place. Anthropic’s own advice is to word your success message as “linked” rather than “billing active”, and I’d take that literally in the UI.
Is Claude linked billing better than asking for the customer’s API key?
For customers with Console accounts and no special data terms, I think so. You never hold their API key, and they get a cap and an exit they control. What it costs you is rate-limit headroom: every linked customer draws on your limits, so one busy tenant can exhaust a shared limit and leave another with 429s.
A customer’s own key sends the request into their organization instead. ZDR is enabled per organization, so that is the direction to look when a customer needs their own data terms, but a key alone doesn’t settle it: workspace settings, the model and the features in use all matter. Confirm it with Anthropic for a regulated customer, because the linked billing guide doesn’t compare the two. If a customer needs HIPAA, FERPA or CMEK coverage for this usage, don’t offer them linked billing.
How do you register a Claude OAuth app for linked billing?
Per the linked billing guide, you do this once, with the Admin role in your Claude organization:
- In the Console under OAuth apps, create an app, set the redirect URI and select Bill and link to organizations.
- On Client authentication, register your identity provider and a subject pattern. Anthropic issues no client secrets, so your back end proves itself with a JWT from that provider.
- Create a service account with a federation rule and select it as the app’s operator service account. This is the identity your back end calls Claude with.
- Choose a default workspace that the service account belongs to. Without one, the code exchange fails with
unauthorized_client, even if you never use per-connection tokens (access tokens tied to one customer’s link, covered below). - To get refresh tokens for those, turn on Offline access on the Permissions tab before customers approve.
- To test, add a person from a second eligible organization to Test users. You can’t link the organization that owns the app, and caps set during testing can’t exceed $50 a month.
- Publish. With invoiced billing the app goes live on confirmation. Otherwise you prove the domain with a DNS TXT record, unless a verified domain already covers it, and Anthropic reviews the app. DNS can take up to 48 hours.
Decide your profile mapping before the first link. Within one app, a customer’s organization links to exactly one of your user profiles, and a profile to one organization. If you already keep a profile per person, Anthropic recommends one more profile for the customer’s organization and linking that.
How do you link a customer’s organization to a Claude OAuth app?
Create a user profile, send a pushed authorization request, redirect the user, then exchange the code. Creating a profile twice makes two profiles even with the same reference_id, so store the ID. Before the request, generate a fresh state and a PKCE verifier of 43 to 128 characters, and store both against the browser session and the customer record:
curl https://auth.claude.com/v1/oauth/par \
-H "content-type: application/json" \
-d '{
"response_type": "code",
"client_id": "YOUR_CLIENT_ID",
"redirect_uri": "https://app.example.com/claude/billing/callback",
"scope": "billing:attribution",
"connection_type": "organization_shared",
"connection_auth_target": "platform",
"user_profile_id": "uprof_01HV9Z",
"state": "RANDOM_STATE",
"code_challenge": "BASE64URL_SHA256_OF_VERIFIER",
"code_challenge_method": "S256",
"client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
"client_assertion": "YOUR_CLIENT_ASSERTION_JWT"
}'Use billing:attribution offline_access as the scope if you want a refresh token. Adding it later means the customer approves again and you replace the stored connection.
Send the browser to https:// with your client_id and the returned request_uri, which expires in 10 minutes. The person approving needs the Admin or Billing role in their organization. On the callback, check state first, and treat an error parameter as no link. The code is single-use and lasts 5 minutes. Exchange it at /v1/oauth/token from your back end with the verifier, and save the token values at once, because they are returned only once.
Tell users to check which Claude account the approval page shows. It offers only that account’s organizations, the organization they pick is the one that pays, and the token response won’t tell you which one it was.
How does billing_policy choose who pays for a Claude request?
With your operator credential, bill_to: "user_profile" charges the customer named in the profile header, and bill_to: "self" or no billing_policy charges you. Any request that sets billing_policy needs the beta header. $OPERATOR_TOKEN here is the service account’s token from your federation rule, not a token from the code exchange:
curl https://api.anthropic.com/v1/messages \
-H "Authorization: Bearer $OPERATOR_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"}
}'A per-connection token follows a different rule. On these endpoints it always bills its own customer, so leaving out billing_policy doesn’t make the request yours, and bill_to: "self" returns a 400.
Python SDK 2.10.0 has typed billing_policy and user_profile_id parameters on client.. In my stub run they did not add the anthropic-beta header by themselves, and with betas=[...] they did, so pass it. The version header is the 2026-10-21 API version, which that SDK sends by default.
Coverage is narrower than the Messages API as a whole. billing_policy works on /v1/messages and /v1/chat/completions, and /v1/ accepts and ignores it. A batch item marked for the customer comes back errored and nobody pays for it, and billable code execution features return a 400 on a customer-billed request. Only mark usage the customer directed: your evals and tests must not go out as user_profile, and the API can’t check that for you.
What should your app do when Claude linked billing refuses a request?
Show the refusal and stop. Don’t resend it on your own bill by default. Anthropic’s rule for a customer-billed request is short:
It never silently bills you instead.These are the responses to handle:
| Response | Meaning | Retry? |
|---|---|---|
403 user_profile_not_billable | your credential, an unlinked profile, an ended link or an ineligible organization; the response doesn’t say which | no, except in the first 10 seconds after a new link |
402 linked_organization_spend_limit_reached | your app’s cap, the organization’s monthly limit, or no credit that can pay; refused before any reply starts | no |
402 linked_organization_billing_unavailable | can’t bill right now, for example a suspended organization or credit running out after the reply has started | no |
503 overloaded_error | billing status couldn’t be confirmed; not served, not billed | yes, with backoff, honoring retry-after |
On /v1/messages the code is in error.details.error_code. On /v1/chat/completions there is no such code, so branch on the HTTP status and error.code, which holds the error type.
For the 403 and both 402s, the docs add that you can resend with bill_to: "self". Wrap that in a generic fallback and you have rebuilt the silent billing Anthropic refused to do: a misconfigured credential produces the same 403 for every customer, and your code quietly moves all of them onto your invoice. So I would never absorb the 403, and absorb a 402 only when something upstream has approved it. This handler is for non-streaming calls with the operator credential:
import anthropic
BILLING_BETA = "user-profiles-billing-2026-10-01"
NOT_BILLABLE = (403, "user_profile_not_billable")
PAYMENT_REFUSED = {
(402, "linked_organization_spend_limit_reached"),
(402, "linked_organization_billing_unavailable"),
}
class BillingRefused(Exception):
def __init__(self, code, request_id):
super().__init__(f"{code} (request {request_id})")
self.code = code
self.request_id = request_id
def create(operator_client, profile_id, bill_to, **params):
return operator_client.beta.messages.create(
betas=[BILLING_BETA],
user_profile_id=profile_id,
billing_policy={"type": "billing_policy", "bill_to": bill_to},
**params,
)
def run_for_customer(operator_client, profile_id, you_approved_paying=False, **params):
try:
reply = create(operator_client, profile_id, "user_profile", **params)
return reply, "customer"
except anthropic.APIStatusError as exc:
refusal = (exc.status_code, exc.error_code)
if refusal != NOT_BILLABLE and refusal not in PAYMENT_REFUSED:
raise
if refusal == NOT_BILLABLE or not you_approved_paying:
raise BillingRefused(exc.error_code, exc.request_id) from exc
return create(operator_client, profile_id, "self", **params), "you"The stub run, one line per case, with what each attempt sent as bill_to:
uprof_ok - ok, payer=customer sent=['user_profile']
uprof_unlinked - BillingRefused user_profile_not_billable sent=['user_profile']
uprof_capped - BillingRefused linked_organization_spend_limit_reached sent=['user_profile']
uprof_suspended - BillingRefused linked_organization_billing_unavailable sent=['user_profile']
uprof_busy - ServiceUnavailableError 503 sent=['user_profile', 'user_profile', 'user_profile']
uprof_typo - BadRequestError 400 sent=['user_profile']
uprof_unlinked approved BillingRefused user_profile_not_billable sent=['user_profile']
uprof_capped approved ok, payer=you sent=['user_profile', 'self']
uprof_suspended approved ok, payer=you sent=['user_profile', 'self']The 503 went out three times because the SDK’s default of two retries runs first, and the handler then passes the last 503 up, so the caller still has to deal with it. you_approved_paying is only a flag. If you want a spending limit behind it, that logic is yours to build, and every absorbed request belongs in your logs.
Two limits apply. The resend needs the operator credential, because a per-connection token can’t send a request you pay for. And when credit runs out after a reply has started, the linked billing docs don’t describe what a streaming client sees or what happens to the partial output. A resend starts over at your cost.
Start a 403 on your own side: check the credential, your profile mapping and the link before you bother the customer. For a 402 limit refusal, send the customer to three places in the Console, because the code doesn’t say which applies: Linked platforms for your app’s cap, Spend limits for the organization’s monthly limit, and Billing for credit. A cap refusal lasts until 00:00 UTC on the first of next month unless they raise or remove the cap, but a new month won’t help an organization that is out of credit.
How do you stop Claude linked billing from charging the wrong customer?
Take the profile ID from your own server-side tenant record, never from anything the client sends. By default your operator credential can bill every linked customer. The docs put the consequence in a warning:
If a request with that credential names a different profile linked through this app, Anthropic bills that profile’s organization, and no error tells you.The structural fix is a per-connection access token, which can bill only its own customer and refuses another profile with a 400. During the beta, though, you have to ask your Anthropic account team whether these tokens are enabled for your organization, and the same goes for the setting that stops the operator credential from billing customers at all. Don’t plan around them until you have that answer. Before you turn that setting on, make sure every customer’s token works, or linked customers start getting 403s.
If you get these tokens, the refresh rules are strict. Access tokens last at most an hour and refresh tokens at most a year, and refreshing doesn’t extend the year. A used refresh token that arrives again more than 30 seconds after its first use ends the connection, revokes every token and leaves the customer unlinked. So refresh from one service, one refresh at a time, with a lock shared across replicas, and turn off automatic retries in your HTTP client and any proxy. Save the new pair before using it. A lost response is the hard case: the guide spells out when one immediate resend is allowed and when you must stop and relink, so implement that list as written. If an agent sandbox calls the API, give it the access token and keep the refresh token on the server.
How do you track who paid for Claude linked billing usage?
Keep your own ledger, because a successful response doesn’t say who was billed. Record the profile, the credential type, the bill_to value and the request-id for every attempt.
Anthropic’s reporting is only a rough check, and it needs an Admin API credential, not your operator service account. On the cost endpoint of the Usage and Cost Analytics API, grouped by user_profile_id, a customer-paid request adds 0 to amount and its list price to list_amount. There is no field or filter for the payer, and per the docs a row with amount 0 and list_amount above 0 usually means the customer paid for all of it. A rising amount on a linked profile is worth an alert, since absorbed requests would show up there, and your ledger tells you whether they were absorbed or simply yours. The data typically refreshes within 4 hours and can take up to 24, so don’t enforce limits from it.
You also get no signal when a customer leaves. Unlinking sends you no webhook and no email. The first sign is a refused request, unless you poll the profile:
curl "https://api.anthropic.com/v1/user_profiles/uprof_01HV9Z?oauth_app_id=YOUR_CLIENT_ID" \
-H "Authorization: Bearer $OPERATOR_TOKEN" \
-H "anthropic-version: 2026-10-21" \
-H "anthropic-beta: user-profiles-search-2026-08-30"connection_status.type reads connected, disconnected or not_connected. Treat a null or unfamiliar value as unknown, and remember that connected doesn’t promise the next request will bill.
What should you check before shipping Claude linked billing?
Check four things: that no customer in scope needs their own ZDR, BAA, HIPAA, FERPA or CMEK terms, that your rate limits can carry their combined traffic, that the profile ID can’t come from the client, and that no code path turns a refusal into bill_to: "self" without an explicit approval behind it. Then get the per-connection token answer from your account team. This is a beta, and Anthropic says endpoints, parameters and behavior can change, so keep the billing code in one module you can rewrite.
01 / Discussion
No comment section here — all discussions happen on X.
02 / More articles
Gemini 4 Carbon cost per task: Google's 2X claim, checked board by board at the December price
Zapier priced Carbon at list, and there the 2X holds. CursorBench and Agent Arena show Carbon at the introductory rate, so their multiples roughly halve on December 1, and the MKA gap Google puts at 6X is 5X in Artificial Analysis's own figures. None of these numbers prices a multi-hour run.
Claude message threads on the Messages API: a thread saves the upload, only the cache saves the prefill
The 35% number is real but narrow: Claude Code traffic at half a million tokens and up. A thread and the prompt cache cut two different costs on two independent clocks, and on the one-hour cache the thread's clock runs out first.
ChatGPT and Codex shared usage limits from December: chat joins the allowance Codex already runs on
Codex already shares its allowance with ChatGPT Work. What December adds is chat, counted in tokens instead of messages, with Instant chat left outside the meter. Whether chat's per-model message caps survive, and how big the combined allowance is, OpenAI hasn't said.