What Anthropic shipped
Anthropic launched linked billing in beta on 17 November 2026, behind the user-profiles-billing-2026-10-01 beta header. A customer of your app approves an OAuth consent screen that links their Claude Platform organisation to your app. After that, your back end sets a billing_policy field on each /v1/messages or /v1/chat/completions request, and that field decides which organisation pays. The request still runs inside your organisation under your rate limits and model access, as Unite.AI's coverage points out.
New Zealand SaaS teams selling AI features to businesses often have to guess a price that covers unpredictable token use. With linked billing, a heavy customer's usage goes on that customer's own Anthropic account in US dollars, and the customer controls the cap. The Next Web presents the feature as a way to pass AI costs on at a time when companies are capping their AI spend.
Who can pay this way
Under the linked billing documentation, only organisations that pay Anthropic directly can be billed, either through prepaid credits or invoiced billing. Organisations billed through AWS, Google Cloud or Azure can't be billed this way, and neither can organisations that only have a Claude subscription plan. The monthly API credits that come with Max, Ultra and Team plans can't pay for these requests either, and nor can partner, VC or startup programme credits. Before you build the linking screen, ask your target customers how they pay Anthropic, because a customer who buys Claude through a cloud marketplace gets a 403 user_profile_not_billable error.
Data terms follow the request, so your organisation's terms apply. Your zero data retention, BAA (a US health-data agreement) and customer-managed encryption key arrangements cover customer-billed traffic, and the customer's own arrangements don't. The docs advise against linking customers who need HIPAA, FERPA or CMEK coverage for this usage.
One-off setup
The docs describe three setup tasks, each needing the Admin role in the Claude Console:
- Create an OAuth app on the Console's OAuth apps page, enter your redirect URI, and turn on Bill and link to organizations. Copy the client ID.
- Configure client authentication. Anthropic doesn't issue a client secret. You register your identity provider, and your back end signs a JWT client assertion, the
private_key_jwtpattern from OAuth. - Create a service account for your back end using Workload Identity Federation, make it the app's operator service account, and set a default workspace. Customers can't link until the default workspace is set.
Linking a customer
Each customer needs a user profile, which is Anthropic's record of which of your end customers a request serves. User profiles shipped on 20 October. The linking flow in the docs looks like this:
- Call
POST /v1/user_profilesonce per customer and store theuprof_...ID. Each call creates a new profile, so reuse the stored ID. - Push an authorisation request to
https://auth.claude.com/v1/oauth/parwith scopebilling:attribution, plusoffline_accessif you want refresh tokens. Include the profile ID, a randomstateand a PKCE S256 challenge. The returnedrequest_urilasts 600 seconds. - Redirect the browser to
https://auth.claude.com/oauth/authorizewith your client ID and therequest_uri. Someone with the Admin or Billing role in the customer's organisation approves the link and can set a monthly spend limit. - On the callback, check
state, then exchange the code, which is valid for five minutes, athttps://auth.claude.com/v1/oauth/token. Store theconnection_idand tokens immediately, because the response returns them only once.
The approval page uses whichever Claude account is signed in to the browser, and your app can't choose that account. Expect some support tickets from users who linked a personal organisation by mistake.
Sending a customer-billed request
The docs show this request:
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"}
}'Setting bill_to to "user_profile" bills the customer. Setting it to "self", or leaving out billing_policy, bills you. The docs limit customer billing to usage the customer directs, so keep your own evals and tests on "self".
The biggest risk is in the credentials. Your operator service account's credential can bill any customer linked through the app, and if you send the wrong profile ID, the wrong organisation pays without any error. A connection's own access token can bill only that customer, but it expires within an hour. Refresh tokens rotate on every use and last at most a year. If a refresh token is reused more than 30 seconds after its first use, the connection ends. Keep refresh tokens out of agent sandboxes and pass sandboxes only the short-lived access token.
Handling refusals
When Anthropic can't bill the customer, the API refuses the request, and your organisation isn't charged for it. The documented errors are:
403 user_profile_not_billable: the customer is ineligible, has unlinked, or your request used the wrong credential. Retry only in the first ten seconds after a new connection.402 linked_organization_spend_limit_reached: the customer hit their cap for your app, hit their organisation's limit, or has no usable credit.402 linked_organization_billing_unavailable: the customer's organisation can't be billed right now.503 overloaded_error: retry with backoff and honourretry-after.
After any of the non-retryable errors, you can resend the request with bill_to: "self" from your own back end and absorb the cost. A successful response doesn't say who paid, so keep your own ledger of customer-billed requests. Anthropic also doesn't notify you when a customer unlinks your app. You get no webhook and no email, so check link status before batches of work.
Spend caps and the testing period
Customers set caps in whole US dollars on their Linked platforms page. A cap counts list prices before any negotiated discount. A customer who hits the cap stays blocked until they raise it or until 00:00 UTC on the first of the next month, which is 1pm in Auckland during daylight saving. While your app is unpublished or in review, every cap must be $50 USD or less. To publish, you need a DNS TXT domain proof and an Anthropic review, unless your organisation already has invoiced billing. Your usage reports show customer-paid requests with an amount of zero and their list price in list_amount. We couldn't find any separate fee for the feature in the docs.
Gaps to plan around
Message Batches can't bill customers. A customer-billed batch item errors, and nobody is charged for it. Customer-billed Messages requests can't use billable code execution. The token-counting endpoint accepts billing_policy and ignores it. Because linked billing is a beta, Anthropic says the endpoints and behaviour may change.
What a builder could do with it
The most practical pattern is a hybrid plan. Your app pays ("self") for a free tier and onboarding, then switches a customer to "user_profile" once they link an organisation for heavier work such as long agent runs or document processing. Internal tools for larger New Zealand firms that already pay Anthropic directly are another good fit, since finance teams can see and cap the spend themselves. If you build something with linked billing, you can share it on the ASAI projects page.
Sources
- Claude Platform release notes
- Linked billing, Claude Platform Docs
- Anthropic Launches Linked Billing Beta for Claude API Apps (Unite.AI)
- Anthropic lets apps bill Claude costs to their customers (The Next Web)
- ASAI Insights feed
- DataForge Insights feed
Build with people working on the same things
Join the Auckland Society for AI: NZ$599 a year with a ForgeBox and the members' projects area. Our Auckland meetups are open to everyone.