◉CLAUDE LABJP
●BILLING — Linked billing entered beta on 11/17: once a customer links their own Claude organization, you choose who pays per request●CC 2.1.326 — Claude Code 2.1.326 (11/16) now warns at startup when an --allowedTools rule looks incomplete●SONNET 4.5 — Retires on the Claude API on 11/30, 12 days left. Sweep model IDs in code and saved settings in one pass●PARALLEL — A user reports overnight parallel sessions using about two-thirds of a weekly allowance●CREDIT — Seeing "Credit balance is too low"? First check whose balance it is: your org, your customer's, or your plan●NEW — Multiply Runs per Day by Tokens per Run Before You Schedule a Job●BILLING — Linked billing entered beta on 11/17: once a customer links their own Claude organization, you choose who pays per request●CC 2.1.326 — Claude Code 2.1.326 (11/16) now warns at startup when an --allowedTools rule looks incomplete●SONNET 4.5 — Retires on the Claude API on 11/30, 12 days left. Sweep model IDs in code and saved settings in one pass●PARALLEL — A user reports overnight parallel sessions using about two-thirds of a weekly allowance●CREDIT — Seeing "Credit balance is too low"? First check whose balance it is: your org, your customer's, or your plan●NEW — Multiply Runs per Day by Tokens per Run Before You Schedule a Job
Articles/API & SDK
⬡ API & SDK/2026-11-18Intermediate

Before Your Customers Pay Through Linked Billing: Reading a 402 or 403 to Find Whose Wallet Is Empty

Linked billing, released in beta on November 17, lets you choose who pays on every Claude API request through billing_policy. When a request billed to a customer comes back as a 402 or 403, here is how I work out which wallet is the cause, when to pay for it myself, and a small Python wrapper that keeps that decision in one place.

Claude API148Linked billingbilling_policybilling9error handling5cost6

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:

  1. 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).
  2. You create a user profile in your own organization to represent that customer.
  3. On each request, the billing_policy field in the body chooses bill_to: "user_profile" (the customer pays) or bill_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.

HTTPerror_codeWhose wallet, and what's missingRetry?
402linked_organization_spend_limit_reachedThe 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 whichNo
402linked_organization_billing_unavailableThe customer's. A suspended organization, or credit that ran out mid-replyNo
403user_profile_not_billableCheck your own side first: how you authenticated, the profile ID header, whether the connection still exists. The customer's organization may also be ineligibleOnly within 10 seconds of a new connection
400user_profile_requiredYours. You set bill_to: "user_profile" without the profile ID headerAfter fixing it
503(overloaded_error)Nobody's. Anthropic couldn't confirm billing right then, and nothing was billedYes, 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.

Share

Thank You for Reading

Claude Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.

  • ✦Copy-paste ready implementation code
  • ✦New advanced guides published daily
  • ✦$5/mo or $10 for lifetime access
View Membership →

If you found this article helpful, a small tip ($1.50) would mean a lot to us. Your support helps keep this site ad-free and covers server and hosting costs.

Related Articles

⬡ API & SDK2026-10-22
You Hit Your Limit and Got a 400 — Telling Apart Your Own Spend Limit, the Tier Cap, and Rate Limits
Claude API limit errors come in three kinds, and they differ in status code and in whether waiting helps. A limit you set returns 400, the tier cap returns 429, and so do ordinary rate limits. Code and a decision table.
⬡ API & SDK2026-04-06
Claude Billing Errors: Fixing "Credit balance is too low," Declined Payments, and Missing Plans
Seeing "Credit balance is too low" from the Claude API, a declined Pro/Max payment, a plan that won't show up, or a charge you don't recognize? Here is the order I check things in, as someone who runs apps on my own.
⬡ API & SDK2026-11-17
If You Rely on Claude's Text Watermark, Check temperature in the Request Body, Not Your Code
Since November 16, text from Opus 4.6, Opus 4.5, Sonnet 4.5, and Haiku 4.5 carries Anthropic's text watermark, but non-default temperature, top_p, or top_k may drop it. Here is how I log the request body once and decide.