Skip to content
sobolewski.proAI today, every eveningSubscribe

Once a day. Unsubscribe with one click. Privacy policy

Linked billing in the Claude API: the customer pays for tokens

Linked billing in the Claude API lets an app charge token costs to the customer's organization instead of the developer. Here's how it works and who it leaves out.

4 min read

This article in other languages:Polski

In this article
  1. How does Linked billing work in the Claude API?
  2. What does the customer control?
  3. Who isn’t covered by Linked billing?
  4. What should we watch out for?
  5. FAQ

On November 17, Anthropic released Linked billing in beta: a customer of an app built on the Claude API can pay for that app’s Claude usage through their own Claude Platform organization. The news is in the Claude Release Notes, and the details are in the Linked billing documentation.

How does Linked billing work in the Claude API?

The customer links their organization to the app once, through OAuth. They give consent on an Anthropic page (auth.claude.com) and need the Admin or Billing role in their organization. The app never receives an API key from them, only a token scoped to that one connection and valid for an hour at most.

From then on, the app’s developer picks who pays on every request to /v1/messages or /v1/chat/completions. That’s done with the billing_policy field and the user-profiles-billing-2026-10-01 beta header:

"billing_policy": {"type": "billing_policy", "bill_to": "user_profile"}

The value user_profile bills the customer, while self (or leaving the field out) bills the developer. If a request marked for the customer can’t be charged to them, the API rejects it instead of quietly billing the developer.

The customer pays Anthropic directly. In the Claude Console and the Usage and Cost Analytics API, the developer sees each profile’s request and token counts, but not how much the customer paid or what rates they have.

What does the customer control?

Right at linking time, the customer can set a monthly spend cap for the app, in whole dollars. Once it’s reached, the API rejects requests billed to the customer with a 402 error, until the first day of the next month (00:00 UTC) or until the cap is raised. The lowest possible cap is $0, which blocks everything.

Connections are managed on the Linked platforms page in the Claude Console. It shows how much the app has cost the organization this month, and it’s where the app can be unlinked at any time. Interestingly, the developer gets no notification when that happens (no webhook, no email) and finds out from a 403 user_profile_not_billable error on the next request.

Who isn’t covered by Linked billing?

The biggest restriction is about who can pay at all. The customer’s organization has to pay Anthropic directly for API usage, from prepaid credits or by invoice. Organizations billed through AWS, Google Cloud or Azure are out, and so are those that only have a Claude subscription.

So Linked billing isn’t a way to use your Max or Ultra plan inside someone else’s app. The documentation says so directly: the monthly API credits from Max, Ultra and Team plans won’t cover these requests, and neither will credits from partner and startup programs.

What should we watch out for?

First, whose organization the requests run in. The customer pays, but the requests execute in the developer’s organization, so its rate limits, its data retention and its encryption settings apply. The documentation advises against linking customers who need HIPAA, FERPA or CMEK for this usage.

Second, the profile header. A request sent with an operator credential that names a different linked profile will bill that profile’s organization with no error at all. A successful response doesn’t say who paid either, so we have to record that on our side.

Third, what can’t be sent at the customer’s expense. Message Batches don’t support this mode, and a request to /v1/messages with paid code execution ends in a 400 error.

Fourth, the testing stage. Until the app is published, only people on its test user list can link to it, and the spend cap is mandatory and tops out at $50 a month. Publishing requires proving domain ownership with a DNS TXT record and a review by Anthropic (unless the developer’s organization is billed by invoice, in which case the app is public right away).

The setup itself isn’t a one-evening job either. Anthropic doesn’t issue a client secret: the backend authenticates with a private_key_jwt assertion from its own identity provider, and the operator’s service account is created through Workload Identity Federation. If we’re only getting started with the API, it’s better to build a regular agent first and leave billing for later ;)

FAQ

Does Linked billing work with a Claude Pro or Max subscription?

No. The customer’s organization has to pay Anthropic directly for the API, from prepaid credits or by invoice. A Claude subscription alone isn’t enough.

Does the customer have to give the app their API key?

No. The customer approves the connection on an Anthropic page, and the app gets an OAuth token that can bill only that one organization.

What happens when the customer hits their spend cap?

The API rejects requests billed to them with a 402 error. The developer can then resend the request at their own expense, with bill_to: "self".

  • AI
  • Anthropic
  • Claude
  • API

AI today, every evening

The day's biggest AI news and new posts from the blog, every evening. Short, with sources.

Once a day. Unsubscribe with one click. Privacy policy