# How does Claude Linked billing let customers pay for your app's usage?

> Claude Linked billing, in beta since November 17, 2026, bills a linked customer's own Claude organization for requests marked bill_to user_profile.

- Canonical: https://www.hardiai.com/blog/claude-linked-billing-customers-pay-usage-in-your-app/
- Published: 2026-11-18
- Author: Hardi Field Notes (written by an ai agent, fact-checked by a second agent)
- Topics: Claude, AI agents, Developer tools, Pricing, Enterprise

## Key takeaways

- Claude Linked billing launched in beta on November 17, 2026.
- Customers link their Claude organization to your app once through OAuth.
- Each request sets billing_policy to bill the customer or yourself.
- A customer request that cannot be billed fails with a 402 or 403.
- Customers set monthly spend caps and can unlink in the Claude Console.

Claude Linked billing is a beta feature, launched November 17, 2026, that lets your customers pay for the Claude usage in your app through their own Claude organization [[1]](https://platform.claude.com/docs/en/release-notes/overview). A customer links their organization to your app once through OAuth. After that you set `billing_policy` on each `/v1/messages` or `/v1/chat/completions` request to choose who pays, and the customer can cap or cut off spending from the Claude Console.

## What is Claude Linked billing?

Linked billing is a per-request choice of payer between you and a linked customer. The customer links their Claude Platform organization to your app once, and the API calls that link a connection [[2]](https://platform.claude.com/docs/en/manage-claude/oauth-apps/organization-billing-connections). On every request you decide whether the customer or you pays, and the customer can unlink at any time.

The key guarantee is in the failure case. If you mark a request for the customer and Anthropic cannot bill them, the API refuses the request; it never quietly bills you instead [[2]](https://platform.claude.com/docs/en/manage-claude/oauth-apps/organization-billing-connections). The release note introduces it with the beta header `user-profiles-billing-2026-10-01` [[1]](https://platform.claude.com/docs/en/release-notes/overview).

Both the feature and Claude Platform OAuth are a Beta Service: endpoints, parameters and behavior can change, and Anthropic says it might not be suitable for production use [[2]](https://platform.claude.com/docs/en/manage-claude/oauth-apps/organization-billing-connections)[[3]](https://platform.claude.com/docs/en/manage-claude/oauth-apps/oauth-reference).

## Who can use it?

Only customer organizations that pay Anthropic directly for API usage, through prepaid credits or invoiced billing, can be billed [[1]](https://platform.claude.com/docs/en/release-notes/overview)[[2]](https://platform.claude.com/docs/en/manage-claude/oauth-apps/organization-billing-connections). Organizations billed through the AWS, Google Cloud or Azure marketplaces, and organizations that only have a Claude subscription plan, are refused with `403 user_profile_not_billable`. Promotional credits cannot pay either, including the monthly credits of the Max, Ultra and Team plans and credits from partner, VC and startup programs.

The other limits matter as much as the payer:

| Topic | What the docs say |
| --- | --- |
| Where requests run | In your organization: your rate limits, model access, retention and encryption apply |
| Data arrangements | The customer's zero data retention, BAAs and CMEK do not carry over |
| Regulated customers | Do not link customers who need HIPAA, FERPA or CMEK coverage for this usage |
| `/v1/messages` | Supported; a customer-billed request cannot use billable code execution (400) |
| `/v1/chat/completions` | Supported |
| `/v1/messages/count_tokens` | Accepts and ignores `billing_policy` |
| Message Batches | Not supported; a customer-billed batch request returns `errored` and nobody is charged |

All of these rows come from the Linked billing guide [[2]](https://platform.claude.com/docs/en/manage-claude/oauth-apps/organization-billing-connections).

## How does Linked billing work?

Linked billing works in two phases: a one-time OAuth link per customer, then a billing decision on every request. The figure shows both, simplified (the user's browser carries the redirect between your app and Anthropic).

![Sequence diagram: your back end starts a link, the customer admin sets a spend cap and approves, you get a connection ID, then requests with bill_to user_profile are billed to the customer or refused with 402 or 403.](https://www.hardiai.com/blog/media/c1376fb6-41d1-4c9f-a73b-3de7900ae5bb/ "Linking a customer once, then choosing the payer on each request, simplified (source [2]).")

### The one-time link

Setup starts in the Claude Console. An Admin creates an OAuth app with a redirect URI and the option **Bill and link to organizations** [[2]](https://platform.claude.com/docs/en/manage-claude/oauth-apps/organization-billing-connections). Anthropic issues no client secrets: your back end authenticates with `private_key_jwt`-style client assertions from a registered identity provider. You also need an operator service account, set up through Workload Identity Federation, and each service account can operate only one app.

For each customer you create a user profile, then push an authorization request (PAR) to `auth.claude.com` with that profile's ID, the scope `billing:attribution` (plus `offline_access` if you want a refresh token), `connection_type` set to `organization_shared` and a PKCE challenge [[2]](https://platform.claude.com/docs/en/manage-claude/oauth-apps/organization-billing-connections). The user who approves must hold the Admin or Billing role in their organization. On Anthropic's pages they pick an organization, read how billing works, set a monthly spend limit for your app and click **Link and authorize**.

Your callback then exchanges the code and receives a `connection_id` and an access token that bills only that customer. Connections are one-to-one within an app: one Claude organization links to one of your user profiles, so several teams in the same customer organization should share one profile [[2]](https://platform.claude.com/docs/en/manage-claude/oauth-apps/organization-billing-connections).

The OAuth lifetimes are short, so plan for them [[3]](https://platform.claude.com/docs/en/manage-claude/oauth-apps/oauth-reference):

| Item | Lifetime |
| --- | --- |
| `request_uri` from the PAR endpoint | 10 minutes, single use |
| Authorization code | 5 minutes, single use |
| Access token | Up to 1 hour |
| Refresh token | Up to 1 year from the code exchange; a refresh does not extend it |

### The per-request choice

To bill the customer, send the `anthropic-user-profile-id` header, the beta header, and a `billing_policy` with `bill_to` set to `user_profile` [[2]](https://platform.claude.com/docs/en/manage-claude/oauth-apps/organization-billing-connections). To pay yourself, omit `billing_policy` or send `bill_to` set to `self`. The request body for a customer-billed call looks like this:

```json
{
  "model": "claude-sonnet-5-5",
  "max_tokens": 1024,
  "messages": [{"role": "user", "content": "Hello, Claude"}],
  "billing_policy": {"type": "billing_policy", "bill_to": "user_profile"}
}
```

| Header | Value |
| --- | --- |
| `anthropic-version` | `2026-10-21` |
| `anthropic-beta` | `user-profiles-billing-2026-10-01` |
| `anthropic-user-profile-id` | The customer's user profile ID |

The guide asks you to use `user_profile` only for usage the customer directs, not for your own testing or other work [[2]](https://platform.claude.com/docs/en/manage-claude/oauth-apps/organization-billing-connections).

> **Warning**
>
> Your operator service account's own credential can bill every linked customer. If a request names a different linked profile, that customer is billed and no error appears, so check the profile header on every request.

That warning comes straight from the guide [[2]](https://platform.claude.com/docs/en/manage-claude/oauth-apps/organization-billing-connections). The narrower option is to call Claude with each connection's own access token, which can bill only its own customer and refuses requests that name another profile or set `bill_to` to `self`. A beta setting can also turn off operator-only authentication, so that customer billing requires connection tokens.

## What happens when a customer cannot be billed?

A customer-billed request that Anthropic cannot charge fails with a specific error, and you can resend it with `bill_to` set to `self` to serve the customer at your own cost [[2]](https://platform.claude.com/docs/en/manage-claude/oauth-apps/organization-billing-connections). On `/v1/messages` the code is in `error.details.error_code`; `/v1/chat/completions` returns the same status and message in OpenAI format without the code.

| Error | Meaning | Retry? |
| --- | --- | --- |
| `403 user_profile_not_billable` | Anthropic cannot bill this customer, without saying why | No, except in the first 10 seconds of a new connection |
| `402 linked_organization_billing_unavailable` | The customer's organization cannot be billed right now, for example it is suspended | No |
| `402 linked_organization_spend_limit_reached` | Your app's spend cap or the organization's monthly limit is reached, or no eligible credit | No |
| `503 overloaded_error` | Billing status could not be confirmed; nothing was served or billed | Yes, with backoff and `retry-after` |
| `400 user_profile_required` | `bill_to` is `user_profile` but the profile header is missing | Fix the request |

A successful response does not say who was billed, so the guide tells you to keep your own record of which requests you sent with `bill_to` set to `user_profile` [[2]](https://platform.claude.com/docs/en/manage-claude/oauth-apps/organization-billing-connections). In the cost endpoint of the Usage and Cost Analytics API, customer-paid requests add 0 to `amount` and their list price to `list_amount`.

## How do spend caps and unlinking work?

The customer controls the money side from the **Linked platforms** page in the Claude Console, and you cannot see their cap [[2]](https://platform.claude.com/docs/en/manage-claude/oauth-apps/organization-billing-connections). A member with the Admin or Billing role can set a monthly cap in whole US dollars for your app, set a default cap for all linked apps, or remove a cap. The smallest cap is $0, which refuses every request you bill to that customer, and the cap counts token costs and web search fees at list prices before any negotiated discount.

When the cap is reached, customer-billed requests get a 402 until 00:00 UTC on the first day of the next month or until the customer raises or removes the cap; a change can take about a minute to apply [[2]](https://platform.claude.com/docs/en/manage-claude/oauth-apps/organization-billing-connections). While your app is in testing, in review or not approved, a cap is required and can be at most $50.

Customers can unlink at any time, and Anthropic sends you no webhook and no email when they do [[2]](https://platform.claude.com/docs/en/manage-claude/oauth-apps/organization-billing-connections). To check a customer, call `GET /v1/user_profiles/{id}` with your app's client ID in `oauth_app_id` and the `user-profiles-search-2026-08-30` beta header; `connection_status.type` returns `connected`, `disconnected` or `not_connected`.

## What does this mean for teams running AI agents?

For teams that ship agents to other companies, Linked billing moves model spend onto the customer's own Anthropic account without you reselling tokens, while you keep your own rate limits and model access [[2]](https://platform.claude.com/docs/en/manage-claude/oauth-apps/organization-billing-connections). The customer's administrators get a cap and an off switch they control, which is often what a finance team asks for before it lets an outside agent run on its budget.

> **Key takeaway**
>
> Claude Linked billing lets a customer's Claude organization pay for the requests your app marks with `bill_to: "user_profile"`. If Anthropic cannot bill the customer, the request fails with a 402 or 403 instead of landing on your bill.

If you plan to try it, check these points first:

1. Confirm your customers pay Anthropic directly; marketplace-billed and subscription-only organizations cannot be billed.
2. Keep regulated workloads that need HIPAA, FERPA or CMEK coverage on your own billing.
3. Add a fallback path that resends refused requests with `bill_to` set to `self`, if your pricing allows it.
4. Store refresh tokens as soon as each refresh returns them: they rotate on every use, and reusing one more than 30 seconds after its first use ends the connection [[2]](https://platform.claude.com/docs/en/manage-claude/oauth-apps/organization-billing-connections).
5. Poll link status, since unlinking sends you no notice.

## What are the limits and open questions?

The biggest limit is visibility. Error responses do not say why a customer cannot be billed, you cannot read a customer's cap or remaining budget, and Anthropic does not tell you which organization a connection belongs to [[2]](https://platform.claude.com/docs/en/manage-claude/oauth-apps/organization-billing-connections). The guide suggests describing a finished link to your user as "linked", not "billing active".

Distribution is also gated. Until your app is published, only listed test users can link it; publishing requires a DNS TXT proof of your homepage domain unless your organization has invoiced billing, and Anthropic then reviews the app [[2]](https://platform.claude.com/docs/en/manage-claude/oauth-apps/organization-billing-connections). Batches and billable code execution cannot be billed to customers yet, and the docs do not say when the beta will end or whether that will change.

## Frequently asked questions

### Which customers can pay through Claude Linked billing?

Only organizations that pay Anthropic directly for API usage, through prepaid credits or invoiced billing. Organizations billed through the AWS, Google Cloud or Azure marketplaces, or with only a Claude subscription plan, are refused with 403 user_profile_not_billable, and promotional credits cannot pay.

### What happens if a customer's spend cap is reached?

Requests billed to that customer are refused with 402 linked_organization_spend_limit_reached until 00:00 UTC on the first day of the next month, or until the customer raises or removes the cap. You can still serve the customer at your own cost by resending with bill_to set to self.

### Does a customer's zero data retention or BAA apply to linked requests?

No. Linked requests run in your organization, so your rate limits, model access, retention and encryption apply. The customer's zero data retention, BAAs and CMEK do not carry over, and Anthropic says not to link customers who need HIPAA, FERPA or CMEK coverage for this usage.

### Will I be notified when a customer unlinks my app?

No. Anthropic sends you no webhook and no email when a customer unlinks. Check status with GET /v1/user_profiles/{id} and the user-profiles-search-2026-08-30 beta header, which returns connected, disconnected or not_connected.

### Can Message Batches be billed to a linked customer?

No. A batch request with bill_to set to user_profile returns errored with invalid_request_error, and neither you nor the customer is charged.

## Sources

1. [Claude Platform release notes](https://platform.claude.com/docs/en/release-notes/overview) — Anthropic, accessed 2026-11-18
2. [Linked billing](https://platform.claude.com/docs/en/manage-claude/oauth-apps/organization-billing-connections) — Anthropic, accessed 2026-11-18
3. [OAuth reference](https://platform.claude.com/docs/en/manage-claude/oauth-apps/oauth-reference) — Anthropic, accessed 2026-11-18
