Anthropic launched Linked billing in beta on 17 November 2026. Third-party apps like Linear, Asana and Railway can now bill their Claude usage straight to your own Claude Platform organization, with no API key changing hands.
This guide has two parts. Part A is for teams who use these apps and want to link, cap or unlink them. Part B is for developers who want to add Linked billing to their own product.
- What: a beta feature that lets a third-party app charge Claude API usage to your Claude Platform organization.
- No key sharing: you approve the app once through Anthropic’s own page, so your API keys never leave your org.
- Control: set a monthly spend cap per app (or a default for all), see each app’s spend, and unlink at any time on the Linked platforms page.
- Who qualifies: only organizations that pay Anthropic directly (prepaid credits or invoice). Cloud marketplace and subscription-only orgs can’t use it.
- Developers: send the
user-profiles-billing-2026-10-01beta header, theanthropic-user-profile-idheader and"billing_policy": {"type": "billing_policy", "bill_to": "user_profile"}.
What Is Claude Linked Billing?
Many work tools now run Claude inside their product. Until now, you had two options. The tool paid for Claude and passed the cost on to you, or you pasted your own Claude API key into the tool.
Linked billing adds a cleaner third option. You link your Claude Platform organization to the tool once. After that, the tool can bill the Claude usage you cause in its product directly to your Anthropic account.
The API calls this link a connection. The Console calls it a link. Both mean the same thing.
Why it matters
- Security: no API key is copied into another company’s system, so there is nothing for them to store, rotate or leak.
- Budget: usage can draw down an existing Anthropic commitment or run pay as you go, instead of buying separate AI credits in every tool.
- Visibility: the Console shows what each linked app costs you this month.
- Control: you can cap or cut off any app yourself, at any time.
Which Apps Support Linked Billing
Anthropic’s launch article lists 19 platforms that support Linked billing today. Here they are, grouped by what they do.
| Category | Platforms |
|---|---|
| Project and work management | Asana, Linear |
| Coding agents and dev tools | Factory, Kilo Code, Warp, Harness, Niteshift |
| Cloud, data and docs | Railway, ClickHouse, Mintlify, Omni |
| Finance and automation | Ramp, Gumloop, Tines |
| Creative and AI apps | Higgsfield AI, OpenArt |
| Other platforms | Major, Runlayer, Tessera |
Each app decides which of its features use your linked account. For example, Higgsfield says Linked billing covers Claude API usage in its Supercomputer feature, while image and video generations still use Higgsfield credits.
Note: the setting usually sits in the app’s workspace, billing or integrations settings, behind a button such as Link your Claude organization. Check the app’s own help page for the exact menu path and which of its plans qualify.
Who Can Use It (Eligibility)
Linked billing only works if your Claude Platform organization pays Anthropic directly for API usage. Use the table to check your setup.
| Your setup | Can you link? |
|---|---|
| Prepaid credits bought in the Claude Console | Yes |
| Invoiced billing with Anthropic | Yes |
| Billed through AWS, Google Cloud or Azure marketplace | No |
| Only a Claude subscription plan (Pro, Max, Team) with no API billing | No |
| Monthly API credits included with Max, Ultra or Team plans | These credits can’t pay for linked usage |
| Partner, VC or startup program credits | These credits can’t pay for linked usage |
You also need the right role. The person who approves must be an Admin or Billing member of the Claude organization (Anthropic’s article also lists Owner). New to the Console? Start with our guide on how to get a Claude API key, which walks through creating an org and adding credits.
Part A: How to Link an App to Your Claude Org
The flow starts inside the third-party app and finishes on Anthropic’s own approval page at auth.claude.com. Each screen shows the app’s name and a Cancel button.
- Open the app’s Claude setting. Find the Link your Claude organization button in the app’s billing or integrations settings and click it.
- Check which Claude account is signed in. The approval page uses whatever Claude account your browser is logged into. If it shows a personal account instead of your work one, switch accounts first.
- Select an organization. This screen only appears if your account belongs to more than one organization. The organization you pick is the one that pays.
- Read “How billing works”. Review the summary and click Continue.
- Set a monthly spend limit. Type a cap in whole US dollars and click Continue. The field starts empty. You can also choose Continue without a limit, and any default cap you saved earlier still applies.
- Approve. The last screen lists what the app will be able to do, including your limit. Click Link and authorize.
- Confirm in the app. You are sent back to the app. Its settings should now show the status as “Linked”.
The link belongs to the whole organization, not to you personally. If you leave the company, the connection stays active until an admin removes it.
Tip: If the app is still in testing with Anthropic, the approval page forces a cap of $50 or less and hides “Continue without a limit”. That is normal for apps that have not been published yet.
Part A: Set, Change or Remove a Spend Cap
After linking, Admin or Billing members manage everything on the Linked platforms page in the Claude Console (platform.claude.com/linked-platforms).
- Set or change a cap: click the app, then Set spend cap or Edit spend cap.
- Set a default cap: under Default spend cap, click Set default or Edit. Every linked app without its own cap can spend up to that amount each month. The apps don’t share it.
- Remove a cap: click the app, then Edit spend cap, then Remove cap. The app falls back to your default, or has no cap if you set none.
How caps behave
- Monthly reset: when an app hits its cap, its requests are refused until 00:00 UTC on the 1st of the next month, or until you raise or remove the cap.
- Quick changes: a cap change takes about a minute to apply.
- Range: the smallest cap is $0, which blocks all billing to you. There is no practical maximum.
- List prices: the cap counts token costs and web search fees at list price, before any discount you have negotiated. Your real bill can differ.
- Two limits: the app cap is separate from your organization’s Monthly spend limit under Settings, Billing. Whichever is hit first stops the app.
Part A: How to Unlink an App
- Open Linked platforms. In the Claude Console, go to the Linked platforms page.
- Pick the app. Click the app you want to remove.
- Unlink it. Choose the unlink option and confirm. The app can no longer bill your organization.
- Tell the vendor if needed. Anthropic does not send the app a webhook or email when you unlink. The app finds out when its next billed request is refused.
Admin and Billing members of your org get an email when your org links an app and when someone unlinks one. The unlink email does not say who did it.
Cost and Privacy: What You Should Know
What you pay
Anthropic’s pages describe no extra fee for linking. Usage is billed to your org at your Anthropic rates, from credits or your invoice. See our Claude API pricing guide for current per-token rates.
The third-party app may still charge for its own product or seats. That part is between you and the vendor.
What the app sees and what it doesn’t
- The app can see: your usage through it, such as request count, tokens and models used.
- The app cannot see: your spend cap, how much of it is used, your rates, or what you actually paid.
- Anthropic doesn’t tell the app: which Claude organization you linked.
Warning: requests still run inside the app’s Claude organization. Your own data settings, such as zero data retention, a BAA, customer-managed encryption keys and IP allowlists, do not apply. Don’t link apps for work that needs HIPAA, FERPA or CMEK coverage.
To track linked spend next to your own API usage, our guide to Claude API cost tracking in the Console covers the reports and spend limits.
Part B: One-Time Developer Setup
Now for builders. Linked billing uses an OAuth app plus Anthropic’s user profiles feature, which launched on 20 October 2026. You need the Admin role in your own Claude organization for setup.
- Create the OAuth app. In the Console, open Settings, OAuth apps, and click Create. Enter the app name and redirect URI. Under What the app can do, select Bill and link to organizations. Copy the client ID.
- Set appearance. On the Appearance tab, set your app name, homepage and logo. Customers see these on the approval page.
- Set up client authentication. On the Client authentication tab, register your identity provider and a subject pattern. Anthropic issues no client secrets. Your back end sends a signed JWT client assertion instead (a
private_key_jwtstyle method). - Create a service account. Follow the Workload Identity Federation guide to create a service account and a second federation rule. Select it as the app’s operator service account. Only this account can bill linked customers.
- Add the scope. On the Permissions tab, under Billing, make sure the app has
billing:attribution. - Publish when ready. New apps start with Test users only. Click Publish app. Invoiced orgs go live at once. Others prove domain ownership with a DNS TXT record and wait for Anthropic’s review.
Note: make sure ANTHROPIC_API_KEY is not set on the back end that runs these calls. Linked billing calls authenticate with Workload Identity Federation, not a plain API key.
Part B: The Customer Linking Flow (OAuth)
For each customer, you run five steps. Connections are one to one: one customer org links to one of your user profiles, and one profile links to one org.
Step 1: Create a user profile
curl https://api.anthropic.com/v1/user_profiles \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "anthropic-version: 2026-10-21" \
-H "content-type: application/json" \
-d '{
"name": "Example Customer Inc.",
"external_user_details": {"reference_id": "your-customer-id-123"}
}'
Store the returned uprof_... ID against the customer record in your product.
Step 2: Create a pushed authorization request
Generate a random state and a PKCE code verifier, then POST to https://auth.claude.com/v1/oauth/par.
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"
}'
You get HTTP 201 with a request_uri that is valid for 600 seconds. The scope must be exactly billing:attribution or billing:attribution offline_access.
Steps 3 and 4: Redirect and let the customer approve
Redirect the browser to https://auth.claude.com/oauth/authorize?client_id=...&request_uri=.... The customer picks an org, sets a cap and clicks Link and authorize, as in Part A.
Step 5: Exchange the code for a connection
curl https://auth.claude.com/v1/oauth/token \
-H "content-type: application/json" \
-d '{
"grant_type": "authorization_code",
"code": "AUTH_CODE",
"code_verifier": "ORIGINAL_CODE_VERIFIER",
"redirect_uri": "https://app.example.com/claude/billing/callback",
"client_id": "YOUR_CLIENT_ID",
"client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
"client_assertion": "YOUR_CLIENT_ASSERTION_JWT"
}'
Check state first. The code is single use and expires after 5 minutes. Save the connection_id (ocon_...) and any tokens now, because they are returned only once.
Tip: show “Linked” in your UI, not “Billing active”. A completed link does not prove the customer’s org is eligible. The first billed request is the real test.
Part B: billing_policy Options With curl and Python
Every call for a linked customer sends the anthropic-user-profile-id header. You then choose, per request, who pays.
| Option | Body field | Beta header | Who pays |
|---|---|---|---|
| Customer pays | "billing_policy": {"type": "billing_policy", "bill_to": "user_profile"} |
Required | Customer’s Claude org |
| You pay (explicit) | "billing_policy": {"type": "billing_policy", "bill_to": "self"} |
Required | Your org |
| You pay (default) | No billing_policy |
Optional | Your org |
curl: bill the customer on /v1/messages
curl https://api.anthropic.com/v1/messages \
-H "Authorization: Bearer $ACCESS_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"}
}'
The same billing_policy field and headers work on the OpenAI-compatible /v1/chat/completions endpoint. The /v1/messages/count_tokens endpoint accepts the field and ignores it.
Python: bill the customer, fall back to yourself
This follows the official pattern. The client authenticates as your operator service account through Workload Identity Federation. New to the SDK? See our Claude API Python tutorial.
import anthropic
client = anthropic.Anthropic() # Workload Identity Federation, no API key
BILLING_BETA = "user-profiles-billing-2026-10-01"
def ask(user_profile_id: str, prompt: str, bill_to: str = "user_profile"):
return client.beta.messages.create(
model="claude-sonnet-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": prompt}],
betas=[BILLING_BETA],
extra_headers={"anthropic-user-profile-id": user_profile_id},
extra_body={"billing_policy": {"type": "billing_policy", "bill_to": bill_to}},
)
try:
msg = ask("uprof_01HV9Z", "Summarise this ticket")
except anthropic.APIStatusError as e:
if e.status_code in (402, 403):
# Customer can't be billed: serve at your own cost (optional)
msg = ask("uprof_01HV9Z", "Summarise this ticket", bill_to="self")
else:
raise
Current limits
- Code execution: requests billed to a customer can’t use billable code execution features. The API returns a 400. Bill those to yourself.
- Message Batches:
bill_to: "user_profile"is not supported. That batch item errors and nobody is billed for it. - Your org’s settings apply: requests run with your rate limits, model access and data retention.
- Use it honestly: only bill the customer for usage they direct, never for your own testing or other customers’ work.
Warning: by default your operator credential can bill every linked customer. If the profile header names the wrong customer, that customer is billed and no error appears. Double-check the mapping, or use per-connection OAuth tokens that can only bill one customer.
Part B: Errors and How to Handle Them
When you set bill_to: "user_profile", Anthropic either bills the customer or refuses. It never silently bills you. On /v1/messages, the code sits in error.details.error_code.
| Status and code | Meaning | What to do |
|---|---|---|
403 user_profile_not_billable |
Customer can’t be billed (not linked, unlinked, ineligible org, wrong credential) | Retry only within 10 s of a new link. Otherwise fix the cause or resend with bill_to: "self". |
402 linked_organization_spend_limit_reached |
App cap, org monthly limit, or no usable credit | Ask the customer to raise the cap or buy credits. Not retryable. |
402 linked_organization_billing_unavailable |
Customer org can’t be billed right now (for example, suspended) | Ask the customer to check their account. Not retryable. |
503 overloaded_error |
Billing status couldn’t be confirmed | Retry with backoff and honour retry-after. |
400 user_profile_required |
bill_to: "user_profile" sent without the profile header |
Add anthropic-user-profile-id. |
| 400 (no code) | Malformed or unknown profile ID, or token misuse | Check the ID belongs to your org. |
A successful response does not say who paid. Keep your own log of which requests used bill_to: "user_profile". For general API errors like 429 and 529, see our Claude API 429 and 529 fix guide.
Troubleshooting: Common Problems and Fixes
- No organization to pick on the approval page: you need the Admin or Billing role in an eligible Claude Platform org. Check the signed-in account, too.
- App says “linked” but nothing is billed to you: your org may be billed through a cloud marketplace or have only a subscription. Those orgs get
user_profile_not_billable. - Requests stop mid-month: your app cap or the org-wide Monthly spend limit was hit, or credits ran out. Raise the cap on Linked platforms or buy credits on the Billing page.
- Just bought credits but still refused: purchases can take a little while to apply. Try again later.
- Cap stuck at $50: the vendor’s app is still in testing or review with Anthropic. The limit lifts once the app is live.
- Developer gets
error=access_denied: the user cancelled, lacks the role, isn’t on your Test users list, or your live app is limited to your own org. The message is the same for all, so ask the user to check. - Developer gets
user_profile_already_linked: that customer org is already linked through another of your profiles. Use that profile, or unlink it and relink. - Code exchange returns
unauthorized_client: set an operator service account and a workspace on the app, wait a minute or two, then retry within the 5-minute code window. - Need to move a customer to another org: unlink first, then run the linking flow again with the same profile. The old cap does not carry over.
Frequently Asked Questions
Is Claude Linked billing free to use?
Anthropic describes no fee for linking itself. You pay for the Claude usage at your normal Anthropic rates, and the third-party app may still charge for its own product.
Does the app get my Claude API key?
No. You approve the app on Anthropic’s own page, and no key changes hands. Your API keys stay inside your organization.
Can I use Linked billing with a Claude Pro or Max subscription?
No. Your org must pay Anthropic directly for API usage with prepaid credits or invoicing. The monthly API credits bundled with Max, Ultra and Team plans can’t pay for linked usage either.
What happens when my spend cap is reached?
The app’s requests billed to you are refused with a 402 until 00:00 UTC on the first of next month, or until you raise or remove the cap. The app may then fall back to its own credits.
Will the app know when I unlink it?
Anthropic sends the app no webhook or email. Its next billed request is refused, and it can check the link status through the API.
Does my zero data retention setting apply to linked usage?
No. Requests run in the app’s organization, so its retention and encryption settings apply, not yours. Avoid linking for HIPAA, FERPA or CMEK workloads.
Which endpoints support billing_policy?
/v1/messages and /v1/chat/completions support it, and /v1/messages/count_tokens accepts and ignores it. Message Batches and billable code execution can’t bill a customer yet.



