On the morning of November 18 I was halfway through making coffee when I saw Linked billing in the Platform release notes. It lets the people who use your app pay for the Claude API through their own Claude organization.
Every time I sketch an AI feature as an indie developer, I stall at the same spot. The more people use it, the more the API bill piles onto one wallet: mine. This looked like it might share that weight at the platform level, so I read the documentation to the end.
The first thing I'd point out is this: once you add Linked billing, the "Credit balance is too low" kind of error has two possible owners. Is it your organization's balance, or your customer's balance or cap? Mix those up and you'll send a customer a "please check your payment" notice for what was really your own configuration mistake.
I haven't linked a real customer yet. What follows is how I sort out refusals, put together from the official documentation and a small piece of test code.
What Linked billing changes
According to the official "Linked billing" guide, the flow looks like this:
- Your customer clicks "Link your Claude organization" in your app and links their Claude organization through OAuth (the person linking needs the Admin or Billing role on their side).
- You create a user profile in your own organization to represent that customer.
- On each request, the
billing_policyfield in the body choosesbill_to: "user_profile"(the customer pays) orbill_to: "self"(you pay).
Requests billed to the customer need the beta header user-profiles-billing-2026-10-01 and an anthropic-user-profile-id header. It works on /v1/messages and /v1/chat/completions. Message Batches can't bill a customer yet.
The part that is easy to miss: the request still runs in your organization. Your rate limits, model access and data retention apply. Zero data retention or a BAA that your customer has arranged does not carry over to these requests.
Money in the customer's account that can't pay
I read the "Which credits can pay" section twice. A request billed to a customer can be paid only by credit bought in the Console or by invoiced billing.
The monthly API credits that come with Max, Ultra and Team plans can't pay for it, and neither can credits from startup or VC programs. From the customer's side the balance looks fine, yet calls through your app are refused. It's the same split-wallet problem I wrote about in "Three balances that don't share a wallet", showing up again.
Organizations that pay through the AWS, Google Cloud or Azure marketplaces, and organizations that only have a Claude subscription, can't be billed at all. Those requests come back as 403 user_profile_not_billable.
A table for telling the wallets apart
What I like about Linked billing is that it never quietly moves a refused charge onto you. You always get a refusal. On /v1/messages, the reason lives in error.details.error_code.
| HTTP | error_code | Whose wallet, and what's missing | Retry? |
|---|---|---|---|
| 402 | linked_organization_spend_limit_reached | The customer's. The cap they set for your app, their organization's monthly spend limit, or no credit that can pay. The response doesn't say which | No |
| 402 | linked_organization_billing_unavailable | The customer's. A suspended organization, or credit that ran out mid-reply | No |
| 403 | user_profile_not_billable | Check your own side first: how you authenticated, the profile ID header, whether the connection still exists. The customer's organization may also be ineligible | Only within 10 seconds of a new connection |
| 400 | user_profile_required | Yours. You set bill_to: "user_profile" without the profile ID header | After fixing it |
| 503 | (overloaded_error) | Nobody's. Anthropic couldn't confirm billing right then, and nothing was billed | Yes, honoring retry-after |
The 403 is where I first went wrong. The name reads like "the customer can't pay", but the documentation's checklist starts with your request. Authenticating as anything other than the operator service account, or sending the ID of a profile that isn't linked, returns the same code. Contact the customer only after you've ruled out your own side.
The line I drew after my first attempt
My first test wrapper treated every 402 and 403 the same way: resend with bill_to: "self". The user never noticed a thing. But in any month a customer hit their cap, everything above that cap would have landed on my bill.
That cap is an amount the customer chose. If I silently absorb it, the cap stops meaning anything, and my own wallet has a bottom too. So I split it like this:
When a cap is reached, stop and tell them. When the plumbing fails, I pay and keep going.
In practice, spend_limit_reached stops and asks the customer to check this app's cap on the Linked platforms page in the Console. billing_unavailable, and a not_billable after I've checked my own side, fall back to bill_to: "self", with a limit on how many times per month.
A wrapper that keeps the decision in one place
The code below sends a request billed to the customer, classifies a refusal, and decides whether to cover it. It's a rough draft written against a test organization, not something I've pointed at real customers.
import anthropic
BILLING_BETA = "user-profiles-billing-2026-10-01"
BILL_CUSTOMER = {"type": "billing_policy", "bill_to": "user_profile"}
BILL_SELF = {"type": "billing_policy", "bill_to": "self"}
# Never absorb a customer's own cap; only cover failures on the billing side
STOP_AND_NOTIFY = {"linked_organization_spend_limit_reached"}
FALLBACK_TO_SELF = {"linked_organization_billing_unavailable", "user_profile_not_billable"}
def error_code_of(err: anthropic.APIStatusError) -> str | None:
body = err.body if isinstance(err.body, dict) else {}
return (body.get("error") or {}).get("details", {}).get("error_code")
def create_for_customer(client, profile_id, messages, model, self_budget):
"""self_budget: how many fallbacks you still allow this month (the caller keeps count)"""
params = dict(model=model, max_tokens=1024, messages=messages, betas=[BILLING_BETA])
try:
msg = client.beta.messages.create(
**params,
extra_headers={"anthropic-user-profile-id": profile_id},
extra_body={"billing_policy": BILL_CUSTOMER},
)
return {"message": msg, "billed_to": "customer"}
except anthropic.APIStatusError as err:
code = error_code_of(err)
if err.status_code == 503:
raise # already past the SDK's own retries; nothing was billed
if code in STOP_AND_NOTIFY:
return {"message": None, "billed_to": None, "notify": "customer_spend_limit"}
if code in FALLBACK_TO_SELF and self_budget > 0:
msg = client.beta.messages.create(**params, extra_body={"billing_policy": BILL_SELF})
return {"message": msg, "billed_to": "self", "reason": code}
return {"message": None, "billed_to": None, "notify": code or f"http_{err.status_code}"}Two notes on why it's written this way.
First, it returns billed_to itself. A successful response doesn't say who was billed, and the documentation tells you to keep your own record of which requests you sent with user_profile. When a customer asks about their bill at the end of the month, that record is the only answer you'll have.
Second, the fallback drops the profile ID header. A per-connection access token is refused if you send bill_to: "self", so the resend has to use the operator service account's own credential. The client above assumes it was built from that credential.
The accident that doesn't raise an error
One warning in the docs made me sit up. The operator credential can bill every customer linked through your app. If you send the wrong customer's profile ID, there's no error; the other customer simply gets billed.
Refusals can be sorted with a table. A mix-up tells you nothing. I stopped looking up the profile ID right before the request and now pass it together with the customer record. Where one token per customer is workable, a per-connection access token, which can only bill its own customer, keeps the blast radius smaller.
When a cap resets
The monthly cap a customer sets for your app is in US dollars, and once it's reached the 402s keep coming. They stop at 00:00 UTC on the first of the next month, or when the customer raises or removes the cap. A cap change takes about a minute to apply.
You can't read the customer's cap or how much of it they've used. So I'd rather not word the notice as "you hit your limit". Listing all three, the app's cap, the monthly spend limit and the credit balance, is the most honest thing the current spec allows. For billing problems in general, see "Fixing Claude billing errors", and for usage-based pricing on top of the API, "Usage-based billing for a B2B SaaS built on Claude".
One thing to try next
Link a second organization of your own as a test customer and set this app's cap to $0. A $0 cap refuses every request billed to that customer. Watching which branch of your code that 402 lands in, once, is what will keep you calm in production.
Keep the border between the customer's wallet and yours in exactly one place in the code. That's the rule I mean to hold on to, however the beta changes.