Claude API Linked Billing: Let Customers Pay for Usage in Your App

TL;DR
Claude API Linked billing (beta, Nov 17, 2026) lets customers pay for Claude usage in your app from their own Claude organization, set per request with billing_policy.
Last updated: November 17, 2026
Anthropic launched Linked billing in beta on November 17, 2026. If you build an app on the Claude API, your customers can now pay for the Claude usage they cause in your app from their own Claude organization instead of you reselling tokens. A customer links once through an OAuth approval page, and from then on you decide per request who pays by adding billing_policy to the request body. If a request you mark for the customer can't be billed to them, the API refuses it rather than billing you.
Everything below comes from the Linked billing docs and the November 17 release note, both read on launch day, plus a type-check of the request against the TypeScript SDK. I did not run a live billed request: that needs a registered OAuth app and a linked customer organization.
Official Sources#
| Resource | What it confirms |
|---|---|
| Claude Platform release notes, November 17, 2026 | Linked billing launch, beta header, billing_policy on /v1/messages and /v1/chat/completions |
| Linked billing guide | Eligibility, setup steps, request format, errors, spend caps |
| User profiles | The per-customer record each billed request names |
| @anthropic-ai/sdk on npm | Version 1.10.0, the first to type billing_policy |
How it works#
Three objects matter. Your OAuth app is registered in the Claude Console with the "Bill and link to organizations" capability. A user profile is a record in your own Claude organization that stands for one customer. A connection links that user profile to the customer's Claude organization after one of their admins approves your app. Connections are one to one: a customer organization links to one of your user profiles, and a user profile links to one organization.
%% title: How a Linked billing request is billed
flowchart TD
A[Your back end calls /v1/messages] --> B{billing_policy.bill_to}
B -->|omitted or self| C[Billed to your organization]
B -->|user_profile| D{Profile linked and customer billable?}
D -->|Yes| E[Billed to the customer's Claude organization]
D -->|No| F[Refused with 403 or 402, nobody billed]
F --> G[Optional: resend with bill_to self at your cost]Setup is three one-time steps, then five per customer. Per the guide:
- Create the OAuth app in the Console (Admin role), with your redirect URI, and copy the public client ID. Anthropic does not issue client secrets.
- Set up client authentication. Your back end proves itself to
auth.claude.comwith a JWT from your own identity provider, a variation ofprivate_key_jwt. - Set up your back end's identity: a service account plus a Workload Identity Federation rule, chosen as the app's operator service account. Only that account can send requests that bill linked customers.
- Per customer: create a user profile, create a pushed authorization request, send the user to the Claude approval page, let them approve (they pick the organization and can set a monthly spend limit for your app), then handle the callback and save the connection.
The person who approves needs the Admin or Billing role in their Claude organization. Until your app is published, only people on its Test users list can link.
Billing a request to the customer#
On each request for a linked customer, send the anthropic-user-profile-id header. To bill the customer, also send the user-profiles-billing-2026-10-01 beta header and billing_policy with bill_to: "user_profile". To pay yourself, omit billing_policy or send bill_to: "self".
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic(); // authenticates as your operator service account
type BillTo = "user_profile" | "self";
// One call for a linked customer. "user_profile" bills the customer's Claude
// organization; "self" bills yours. A refused customer-billed request is never
// silently billed to you.
async function ask(userProfileId: string, prompt: string, billTo: BillTo) {
return client.beta.messages.create({
model: "claude-sonnet-5-5",
max_tokens: 1024,
messages: [{ role: "user", content: prompt }],
betas: ["user-profiles-billing-2026-10-01"],
user_profile_id: userProfileId, // sent as the anthropic-user-profile-id header
billing_policy: { type: "billing_policy", bill_to: billTo },
});
}
export async function replyForCustomer(userProfileId: string, prompt: string) {
try {
return await ask(userProfileId, prompt, "user_profile");
} catch (err) {
// 403 user_profile_not_billable, or 402 when the customer can't pay.
const refused =
err instanceof Anthropic.PermissionDeniedError ||
(err instanceof Anthropic.APIError && err.status === 402);
if (!refused) throw err;
// Your call: serve them at your own cost, or surface the error.
return ask(userProfileId, prompt, "self");
}
}
What I checked. Against @anthropic-ai/sdk 1.10.0 (published November 17, 2026), this passes tsc --noEmit --strict (TypeScript 5, moduleResolution: nodenext). In 1.10.0, billing_policy is typed as BetaBillingPolicy, and bill_to is 'self' | 'user_profile', so bill_to: "customer" fails with TS2769. The same file fails against 1.9.0, which doesn't know the field, so upgrade before you adopt it. One trap: the TypeScript example in the docs still carries // @ts-expect-error: billing_policy isn't in the SDK's types yet. On 1.10.0 strict tsc reports that directive as unused (TS2578), so remove it when you copy the example.
The fallback in replyForCustomer is a product decision, not a requirement. The docs say you "can still serve the customer at your own cost by resending with bill_to: "self"". Note that the PermissionDeniedError class also matches other 403s. The docs say to check error.details.error_code for user_profile_not_billable before you treat it as a billing refusal.
Errors to handle#
When a request sets bill_to: "user_profile", Anthropic "either bills your customer or refuses the request. It never silently bills you instead." The codes on /v1/messages, from the guide:
| Status and code | Meaning | Retry? |
|---|---|---|
403 user_profile_not_billable | Anthropic can't bill this customer for this request; the response doesn't say why | No, except in the first 10 seconds after a new connection |
402 linked_organization_billing_unavailable | The customer's organization can't be billed right now, for example it's suspended | No |
402 linked_organization_spend_limit_reached | The customer hit the spend cap for your app, their organization's monthly limit, or has no credit that can pay | No |
503 overloaded_error | Anthropic couldn't confirm the customer can be billed | Yes, with backoff and retry-after |
400 user_profile_required | bill_to: "user_profile" without the profile header | Fix the request |
A successful response doesn't say who was billed, so keep your own record of which requests you sent with bill_to: "user_profile".
Spend caps#
The user who links can set a monthly cap for your app in whole US dollars, and the customer's Admin or Billing members can change it later on the Linked platforms page. You can't read a customer's cap or how much of it they have used. When the cap is reached, requests you bill to them get a 402 until 00:00 UTC on the first of the next month or until they raise the cap. A cap of $0 refuses every request you bill to that customer.
Gotchas before you ship it#
- Requests run in your organization. Your rate limits, model access, data retention and encryption keys apply. The customer's own arrangements, including zero data retention, a BAA and customer-managed keys, do not. The guide says not to link customers that need HIPAA, FERPA or CMEK coverage for this usage.
- Not every customer is eligible. Only organizations that pay Anthropic directly (prepaid credits or invoicing). Marketplace-billed organizations on AWS, Google Cloud or Azure, and subscription-only organizations, get 403
user_profile_not_billable. - Not every credit pays. Some promotional credits can't pay for these requests, including the monthly API credits that come with Claude Max, Ultra and Team plans, and credits from partner, VC and startup programs.
- Not every endpoint is supported.
billing_policyworks on/v1/messagesand/v1/chat/completions. Message Batches refusebill_to: "user_profile", and a customer-billed/v1/messagesrequest can't use billable code execution features (it returns a 400). - Your operator credential can bill any linked customer. If a request names the wrong profile, that customer is billed and no error tells you. The guide's fix is OAuth tokens scoped to one connection, which can bill only their own customer.
- Unlinking is silent. Customers can unlink on their Linked platforms page at any time, and Anthropic sends you no webhook or email. Your next billed request gets 403
user_profile_not_billable. - It's a beta. The guide warns that "endpoints, parameters, and behavior can change during the beta" and that it "might not be suitable for production use."
When to use it#
Linked billing fits apps whose users are mostly Claude Platform customers already: developer tools, internal-platform vendors and agent products sold to teams that have their own Anthropic accounts. It removes the reselling problem (estimating usage, marking up tokens, eating overages) for those customers, and the customer keeps control through the spend cap. If most of your users are consumers or companies billed through a cloud marketplace, it won't cover them, and you keep paying for their usage as before. If you also run agents server-side, the self-hosted Managed Agents launch from five days earlier is the other recent change to how Claude usage is run and paid for.
FAQ#
What is Linked billing in the Claude API?#
A beta, launched November 17, 2026, that lets your customers pay for the Claude usage in your app through their own Claude organization. A customer links their organization to your app once through an OAuth approval page, and then you choose on each request, with the billing_policy field, whether the customer or you pays.
How do I bill a request to the customer?#
Send the user-profiles-billing-2026-10-01 beta header, the anthropic-user-profile-id header with the customer's user profile ID, and billing_policy set to {"type": "billing_policy", "bill_to": "user_profile"} in the body of a /v1/messages or /v1/chat/completions request. Omit billing_policy, or send bill_to: "self", to pay yourself.
What happens if the customer cannot be billed?#
The request is refused, never billed to you. The API returns 403 user_profile_not_billable or a 402 billing_error such as linked_organization_spend_limit_reached. You can resend with bill_to: "self" to serve the customer at your own cost.
Which customers are eligible for Linked billing?#
Only Claude Platform organizations that pay Anthropic directly for API usage, with prepaid credits or invoicing. Organizations billed through AWS, Google Cloud or Azure marketplaces, and organizations with only a Claude subscription plan, are refused with 403 user_profile_not_billable.
Does the TypeScript SDK support billing_policy?#
Yes, from @anthropic-ai/sdk 1.10.0, released November 17, 2026, which types billing_policy as BetaBillingPolicy on client.beta.messages.create. On 1.9.0 the field fails type-checking. The docs example still carries a @ts-expect-error comment, which strict tsc reports as unused on 1.10.0.
Sources#
- Claude Platform release notes, November 17, 2026 - the launch note
- Linked billing guide - setup, request format, errors, spend caps
- User profiles for end-customer attribution - the record each billed request names
- Workload Identity Federation - the service account setup in Step 3
- @anthropic-ai/sdk on npm - version 1.10.0, the build type-checked here
Continue Reading#
- Claude API version 2026-10-21: SDK migration - the API version the Linked billing examples send
- Claude API message threads - another recent beta on the Messages API
- Self-hosted Claude Managed Agents - run the Managed Agents service on your own infrastructure
- Claude API tracing with OpenTelemetry - track per-customer usage on your side, since responses don't say who was billed
- Claude Code tool page - Anthropic's coding agent, setup and pricing links
Get the next deep dive like this in your inbox
One email a week on Anthropic and the rest of the AI dev stack. Free.
Read next on Claude Code
Claude API 2026-10-21: Breaking Changes and SDK Migration
Claude API version 2026-10-21 removes temperature, top_p and top_k, and new major SDKs (TypeScript 1.0, Python 2.0) send it by default. What breaks and how to migrate.
9 min readClaude API Message Threads: Send Only the New Turn (Beta Guide)
Claude API message threads (beta, Nov 2) keep a conversation on the server for 5 minutes, so each turn sends only new messages. Setup, SDK helper, errors, limits.
9 min readSelf-Hosted Claude Managed Agents: What You Run and What You Lose
Self-hosted Claude Managed Agents runs the service, its PostgreSQL store and sandboxes on your infra, with Bedrock, Vertex, Foundry or a gateway for model calls.
8 min readTechnical content at the intersection of AI and development. Building with AI agents, Claude Code, and modern dev tools - then showing you exactly how it works.






