Linked billing: let your customers pay for the Claude usage in your app
In brief
On November 17, 2026 Anthropic launched linked billing in beta. A customer links their Claude Platform organization to your app once, and from then on you choose per request whether they pay or you do. No API key changes hands. How the link works, the request shape, the three errors to handle, and what the customer's admin should check before approving.
Contents
On November 17, 2026, Anthropic launched linked billing on the Claude Platform. It is in beta, so endpoints and parameters can change.
Linked billing lets a customer of your app pay Anthropic directly for the Claude usage your app runs for them. The customer links their Claude Platform organization to your app once. After that, each request you send says who pays: the customer or you.
Until now, a product that wanted customers to cover their own Claude costs had two choices. It could ask each customer to paste in an API key ("bring your own key"), then store, encrypt, and rotate those keys. Or it could pay Anthropic itself and re-bill customers with a markup. Linked billing is a third route: no key changes hands, and the usage shows up on the customer's own Anthropic bill.
Nineteen platforms supported it at launch, including Asana, Linear, Warp, Railway, Ramp, Mintlify, Factory, and Kilo Code. Customers can find participating apps on Claude Marketplace.
Two readers, two jobs
- You build an app that calls Claude for your customers. Most of this article is for you: setup, the request shape, and the errors.
- You are an admin whose vendor is asking you to "link your Claude organization." Skip to the section "If a vendor asks you to link" near the end.
How it works
- You register an app in the Claude Console.
- Your customer's admin approves the link on a page Anthropic hosts, and can set a monthly spend limit for your app.
- You send requests with a
billing_policyfield. Withbill_to: "user_profile", the customer's organization is billed. Without it, you are. - The customer sees what your app cost them in their Console and can unlink at any time.
The link is called a connection. It joins one user profile in your organization to one customer organization. A user profile is the record you create for an end customer; it is the same object used for per-customer safety enforcement. If you already create profiles, you reuse them here.
Connections are one-to-one. A customer organization can link to only one of your profiles, and a profile can link to only one organization.
Who can be billed
| Customer's situation | Can they pay through linked billing? |
|---|---|
| Pays Anthropic directly, with prepaid Console credits or invoiced billing | Yes |
| Billed through AWS, Google Cloud, or Azure | No |
| Has only a Claude subscription plan, with no API billing set up | No |
Some credits cannot pay for linked usage either: the monthly API credits that come with Max, Ultra, and Team plans, and credits from partner, VC, and startup programs.
What runs where
This is the part to read twice. A linked request runs in your organization. The customer only pays for it.
| Setting | Whose applies |
|---|---|
| Rate limits, model access, service tier | Yours |
| Data retention, encryption keys | Yours |
| Customer's zero data retention, BAA, customer-managed keys, IP allowlists | Do not apply |
| The bill | The customer's |
Anthropic's docs say plainly: do not link customers who need HIPAA, FERPA, or customer-managed key coverage for this usage.
One-time setup
You need the Admin role in your Console organization.
- Create the app. On the Console's OAuth apps page, enter a name and redirect URI. Under What the app can do, select Bill and link to organizations. Copy the client ID. The app starts in testing, where only the test users you list can link.
- Set up client authentication. Anthropic issues no client secret. Your back end proves its identity with a signed token (a JWT) from your own identity provider. You register the issuer and a subject pattern in the app's settings.
- Create a service account. Create a service account and a Workload Identity Federation rule, then select it as the app's operator service account. This is the identity your back end uses to call the Claude API. One service account can operate only one app.
The linked billing docs have the full walkthrough with samples in seven languages.
Linking a customer
For each customer, once:
- Create or reuse a user profile. Store the
uprof_...ID against the customer in your database. Every create call makes a new profile, so do not create one on each attempt.
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"}}'
- Start an authorization request. Your back end posts to
https://auth.claude.com/v1/oauth/parwith your client ID, redirect URI, the profile ID,scopeset tobilling:attribution,connection_typeset toorganization_shared, and a PKCE challenge. You get back arequest_urithat lasts 10 minutes. - Redirect the customer's browser to
https://auth.claude.com/oauth/authorizewith yourclient_idand thatrequest_uri. - The customer approves. They sign in, pick an organization, read how billing works, optionally set a monthly spend limit, and click Link and authorize. The person approving needs the Admin or Billing role in their organization.
- Exchange the code. The browser returns to your redirect URI with a
code. Your back end posts it tohttps://auth.claude.com/v1/oauth/tokenwithin 5 minutes and receives aconnection_id(ocon_...). Store it.
The approval page uses whichever Claude account is signed in to the browser. If your contact is signed in to a personal account, they will not see their work organization. Tell them to check before they click your "Link" button.
Sending a request the customer pays for
Three things mark a request as customer-paid: the beta header, the profile ID header, and billing_policy in the body.
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"}
}'
bill_to has two values:
"user_profile": the customer linked to the profile in the header pays."self": you pay. Leavingbilling_policyout means the same thing.
The same call from Python. The client authenticates as your operator service account, and the SDK passes the extra headers and body field through:
import anthropic
client = anthropic.Anthropic() # authenticates as your operator service account
def ask(profile_id: str, prompt: str, customer_pays: bool):
extra_body = {}
if customer_pays:
extra_body["billing_policy"] = {"type": "billing_policy", "bill_to": "user_profile"}
return client.messages.create(
model="claude-sonnet-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": prompt}],
extra_headers={
"anthropic-beta": "user-profiles-billing-2026-10-01",
"anthropic-user-profile-id": profile_id,
},
extra_body=extra_body,
)
A successful response does not say who was billed. Record it yourself: write bill_to next to each request in your own logs.
Which endpoints accept it
| Endpoint | Customer-paid requests |
|---|---|
/v1/messages |
Supported. A customer-paid request that uses billable code execution returns a 400. |
/v1/chat/completions |
Supported |
/v1/messages/count_tokens |
Field accepted and ignored |
/v1/messages/batches |
Not supported. The batch item comes back errored and nobody is billed. |
The mistake that bills the wrong customer
Your operator service account can bill any customer linked to your app. If a bug puts customer A's profile ID on customer B's request, Anthropic bills customer A and returns no error.
Two defences:
- Resolve the profile ID on the server from the authenticated session. Never accept it from the browser or from a request parameter.
- Use connection-bound tokens for higher-risk paths. If you add
offline_accessto the scope when linking, the code exchange also returns an access token and refresh token that can bill only that one customer. Naming a different profile with that token returns a 400. The tokens are returned once, so store them immediately. Refresh tokens rotate on every use, and reusing an old one more than 30 seconds later ends the connection, so turn off automatic retries on the refresh call.
Only set bill_to: "user_profile" on requests the customer directed. Your own testing, evals, and background jobs for other customers go on your bill.
Three errors to handle
When you ask Anthropic to bill the customer, it either bills them or refuses the request. It never falls back to billing you silently. On /v1/messages the code is in error.details.error_code.
| Status and code | What it means | What to do |
|---|---|---|
403 user_profile_not_billable |
Anthropic cannot bill this customer. The response does not say why. | Check your credential and profile ID first, then whether the customer is still linked. Not retryable, except in the first 10 seconds after a new link. |
402 linked_organization_spend_limit_reached |
The customer hit the spend cap for your app, their organization-wide monthly limit, or has no eligible credit. | Tell the customer to check their cap and credit balance in the Console. Lasts until 00:00 UTC on the first of next month, or until they raise the cap. |
402 linked_organization_billing_unavailable |
The customer's organization cannot be billed right now, for example because it is suspended. | Tell the customer to check their Claude Platform account. |
A 503 overloaded_error means Anthropic could not confirm billing; retry with backoff. Nothing was served or billed.
For every one of these you have the same fallback: resend the request with bill_to: "self" and absorb the cost. Decide in advance which you want. A reasonable default is to fall back for a short grace period and show the customer a banner, so a spend cap does not look like an outage in your product.
import anthropic
def ask_with_fallback(profile_id: str, prompt: str):
try:
return ask(profile_id, prompt, customer_pays=True), "customer"
except anthropic.APIStatusError as e:
body = e.body if isinstance(e.body, dict) else {}
code = body.get("error", {}).get("details", {}).get("error_code")
billing_refusals = {
"user_profile_not_billable",
"linked_organization_spend_limit_reached",
"linked_organization_billing_unavailable",
}
if e.status_code in (402, 403) and code in billing_refusals:
notify_customer(profile_id, code) # your own banner or email
return ask(profile_id, prompt, customer_pays=False), "self"
raise
What you cannot see
- The customer's spend cap, or how much of it is used. You find out when you get the 402.
- When a customer unlinks. There is no webhook and no email to you. Check link status with
GET /v1/user_profiles/{id}?oauth_app_id=YOUR_CLIENT_IDand theuser-profiles-search-2026-08-30beta header.connection_status.typeisconnected,disconnected, ornot_connected. - Who paid, from the usage API. The Usage and Cost Analytics API can group by
user_profile_id, but has no field for who was billed. In the Console, customer-paid requests add 0 to the Your spend column.
Going live
While your app is in testing, only listed test users can link, and each must set a cap of $50 or less. To publish:
- Organizations on invoiced billing publish immediately after confirming.
- Everyone else proves control of their domain with a DNS TXT record, and Anthropic reviews the app.
Changing a live app's name, logo, homepage, or redirect URIs triggers a new review. Customers who are already linked stay linked.
If a vendor asks you to link
You are the customer's admin. A vendor's app wants to bill its Claude usage to your organization. Before you click Link and authorize:
- Set a spend limit on the approval screen. The field starts empty, and Continue without a limit means no cap for this app. Enter a number. You can change it later under Linked platforms in the Claude Console.
- Set a default cap for all linked apps. Under Linked platforms, set Default spend cap. Every linked app without its own cap gets that amount per month. Each app gets the full amount; they do not share it.
- Know what the cap counts. It counts token costs and web search fees at list prices, before any discount you negotiated. Your actual bill can be lower than what the cap counted.
- Ask the vendor about data handling. The requests run in the vendor's organization. Your zero data retention agreement, BAA, customer-managed keys, and IP allowlists do not cover them. The vendor's retention settings do.
- Check who gets the emails. Anthropic emails members with the Admin or Billing role when an app is linked or unlinked. Make sure a monitored inbox holds one of those roles.
You can unlink any app from Linked platforms at any time. The vendor's customer-paid requests are refused from then on.
Should you offer it?
Linked billing fits when your customers already buy from Anthropic directly and want Claude costs on one bill with their own limits. It replaces bring-your-own-key without the key storage.
It fits poorly in three cases:
- Your customers buy Claude through AWS, Google Cloud, or Azure. They are not eligible.
- You make margin on tokens. The customer pays Anthropic's price to Anthropic. Your revenue has to come from your own subscription or seat price.
- Your heavy usage runs through the Batch API. Batches cannot be customer-paid.
A practical first step: add linking as an option next to your existing billing, link one test organization with a $50 cap, and run the three error paths on purpose before you publish the app.
Sources: Linked billing on the Claude Platform (Anthropic, November 17, 2026) and the linked billing docs.