Max Narditdata & ai systems
← Articles
10 mindev

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 chargethe customer’s organization
Optional monthly spend cap for your appthe customer’s, and you can’t read it
Rate limits, model access, service tieryours
Data retention and encryption keysyours
The customer’s ZDR, BAA, CMEKdon’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:

  1. In the Console under OAuth apps, create an app, set the redirect URI and select Bill and link to organizations.
  2. 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.
  3. 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.
  4. 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).
  5. To get refresh tokens for those, turn on Offline access on the Permissions tab before customers approve.
  6. 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.
  7. 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.

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:

shell
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://auth.claude.com/oauth/authorize 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:

shell
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.beta.messages.create. 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/messages/count_tokens 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:

ResponseMeaningRetry?
403 user_profile_not_billableyour credential, an unlinked profile, an ended link or an ineligible organization; the response doesn’t say whichno, except in the first 10 seconds after a new link
402 linked_organization_spend_limit_reachedyour app’s cap, the organization’s monthly limit, or no credit that can pay; refused before any reply startsno
402 linked_organization_billing_unavailablecan’t bill right now, for example a suspended organization or credit running out after the reply has startedno
503 overloaded_errorbilling status couldn’t be confirmed; not served, not billedyes, 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:

python
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:

shell
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.

Max Nardit@mnardit

02 / More articles