Max Nardit
← Artikel
10 mindev

Claude Linked Billing: Mit billing_policy zahlt der Kunde, der Request läuft aber weiter in deiner Organisation

Ein falsch gedeuteter 403 kann alle Mandanten auf deine Rechnung schieben, ein falscher Header belastet jemand anderen. Wo diese Fehler stecken und was du zuerst loggen solltest.

Inhalt

Mit Claude Linked Billing, das Anthropic am 17. November 2026 als Beta gestartet hat, verknüpft ein Kunde seine Claude-Organisation mit deiner App und bezahlt die Claude-Nutzung, die er dort auslöst. Verschoben wird nur die Abrechnung: Der Request läuft weiter in deiner Organisation, mit deinen Rate Limits, deinem Modellzugang und deinen Aufbewahrungsregeln. Auch die Garantie, wer zahlt, geht leichter verloren, als es aussieht. Anthropic lehnt einen auf den Kunden abgerechneten Request ab, statt ihn dir zu berechnen, und die Doku ergänzt dann, dass du ihn mit bill_to: "self" erneut senden kannst. Steckt dieser zweite Versuch in einem generischen Fallback, schiebt ein einziges falsch konfiguriertes Credential alle Kunden auf deine Rechnung, ohne dass irgendwo ein Fehler auftaucht.

Den echten Ablauf habe ich nicht durchgespielt. Dafür bräuchte es eine registrierte OAuth-App, Workload Identity Federation und eine zweite berechtigte Organisation. Die Protokolldetails unten stammen aus Anthropics Doku, Stand 19. November. Den Error-Handler habe ich tatsächlich ausgeführt, mit dem Python SDK 2.10.0 gegen einen lokalen Stub, der die dokumentierten Fehler zurückgibt. Das zeigt also, wie sich mein Code verhält, und sagt nichts über Anthropics Server. Die Empfehlungen sind meine Lesart.

Was verschiebt Claude Linked Billing zum Kunden?

Die Abrechnung und fast nichts sonst. Anthropic belastet die Organisation des Kunden für die Requests, die du entsprechend markierst, und der Kunde kann für deine App ein monatliches Ausgabenlimit setzen oder die Verknüpfung lösen. Wie der Request bedient wird, bleibt bei dir:

Wem es bei einem auf den Kunden abgerechneten Request gehört
Die Abrechnungder Organisation des Kunden
Optionales monatliches Ausgabenlimit für deine Appdem Kunden, und du kannst es nicht auslesen
Rate Limits, Modellzugang, Service Tierdir
Datenaufbewahrung und Verschlüsselungsschlüsseldir
ZDR, BAA, CMEK des Kundengelten nicht

Die letzte Zeile solltest du deinen Vertriebs- und Security-Leuten zeigen. Ein Kunde mit Zero Data Retention in seiner eigenen Organisation nimmt vielleicht an, dass sie der Rechnung folgt. Das tut sie nicht, und die Doku rät davon ab, Kunden zu verknüpfen, die für diese Nutzung HIPAA-, FERPA- oder CMEK-Abdeckung brauchen.

Welche Organisationen können Claude Linked Billing nutzen?

Beide Seiten müssen direkt an Anthropic zahlen. Deine eigene Organisation auch, sonst scheitern auf den Kunden abgerechnete Requests mit einem 403 ohne Fehlercode. Die Organisation des Kunden muss die API-Nutzung per Prepaid-Guthaben oder Rechnung bezahlen. Organisationen, die über die Marketplaces von AWS, Google Cloud oder Azure abgerechnet werden, fallen raus, ebenso solche, die nur einen Claude-Abo-Plan haben. Ihre Requests bekommen 403 user_profile_not_billable.

Auch die Art des Guthabens zählt. In der Console gekauftes Guthaben kann zahlen. Die monatlichen API-Credits aus den Plänen Max, Ultra und Team können es nicht. Das Guthaben, das du vielleicht mit einem dieser Pläne abgeholt hast, reicht also nicht, und Credits aus Anthropics Partner-, VC- und Startup-Programmen genauso wenig.

Eine Verknüpfung kann auch dann zustande kommen, wenn nichts davon erfüllt ist. Anthropic rät selbst, die Erfolgsmeldung mit „verknüpft“ zu formulieren und nicht mit „Abrechnung aktiv“, und das würde ich in der Oberfläche wörtlich nehmen.

Ist Claude Linked Billing besser, als den API-Key des Kunden zu verlangen?

Für Kunden mit Console-Konto und ohne besondere Datenbedingungen meiner Meinung nach ja. Du verwahrst nie ihren API-Key, und sie bekommen ein Limit und einen Ausstieg, den sie selbst kontrollieren. Bezahlen musst du das mit Spielraum bei den Rate Limits: Jeder verknüpfte Kunde zehrt von deinen Limits, ein einzelner aktiver Mandant kann also ein gemeinsames Limit ausschöpfen und einem anderen 429er bescheren.

Mit dem eigenen Key des Kunden landet der Request dagegen in seiner Organisation. ZDR wird pro Organisation aktiviert, in diese Richtung solltest du also schauen, wenn ein Kunde eigene Datenbedingungen braucht. Der Key allein klärt das aber nicht: Workspace-Einstellungen, das Modell und die genutzten Features spielen alle mit. Kläre das bei einem regulierten Kunden mit Anthropic, denn der Linked-Billing-Guide vergleicht die beiden Wege nicht. Braucht ein Kunde für diese Nutzung HIPAA-, FERPA- oder CMEK-Abdeckung, biete ihm Linked Billing nicht an.

Wie registrierst du eine Claude-OAuth-App für Linked Billing?

Laut Linked-Billing-Guide machst du das einmal, mit der Admin-Rolle in deiner Claude-Organisation:

  1. Lege in der Console unter OAuth apps eine App an, setze die Redirect-URI und wähle Bill and link to organizations.
  2. Registriere unter Client authentication deinen Identity Provider und ein Subject Pattern. Anthropic stellt keine Client Secrets aus, dein Backend weist sich also mit einem JWT dieses Providers aus.
  3. Erstelle einen Service Account mit einer Federation Rule und wähle ihn als Operator Service Account der App. Mit dieser Identität ruft dein Backend Claude auf.
  4. Wähle einen Standard-Workspace, zu dem der Service Account gehört. Ohne ihn scheitert der Code-Austausch mit unauthorized_client, selbst wenn du nie Per-Connection-Tokens nutzt (Access Tokens, die an die Verknüpfung eines einzelnen Kunden gebunden sind, dazu unten mehr).
  5. Für Refresh Tokens zu diesen Tokens schalte auf dem Tab Permissions die Option Offline access ein, bevor Kunden zustimmen.
  6. Zum Testen fügst du unter Test users eine Person aus einer zweiten berechtigten Organisation hinzu. Die Organisation, der die App gehört, kannst du nicht verknüpfen, und Limits während der Tests dürfen 50 Dollar im Monat nicht übersteigen.
  7. Veröffentliche die App. Bei Abrechnung per Rechnung geht sie mit der Bestätigung live. Sonst weist du die Domain über einen DNS-TXT-Eintrag nach, sofern nicht schon eine verifizierte Domain sie abdeckt, und Anthropic prüft die App. DNS kann bis zu 48 Stunden dauern.

Lege die Zuordnung der Profile vor der ersten Verknüpfung fest. Innerhalb einer App wird die Organisation eines Kunden mit genau einem deiner User Profiles verknüpft und ein Profil mit einer Organisation. Führst du bereits ein Profil pro Person, empfiehlt Anthropic ein zusätzliches Profil für die Organisation des Kunden, das du dann verknüpfst.

Wie verknüpfst du die Organisation eines Kunden mit einer Claude-OAuth-App?

Profil anlegen, Pushed Authorization Request senden, Nutzer weiterleiten, Code eintauschen. Legst du ein Profil zweimal an, entstehen auch bei gleicher reference_id zwei Profile, speichere also die ID. Erzeuge vor dem Request einen frischen state und einen PKCE-Verifier mit 43 bis 128 Zeichen und speichere beide zur Browser-Session und zum Kundendatensatz:

shell
curl https://auth.claude.com/v1/oauth/par \
  -H "content-type: application/json" \
  -d '{
    "response_type": "code",
    "client_id": "YOUR_CLIENT_ID",
    "redirect_uri": "https://app.example.com/claude/billing/callback",
    "scope": "billing:attribution",
    "connection_type": "organization_shared",
    "connection_auth_target": "platform",
    "user_profile_id": "uprof_01HV9Z",
    "state": "RANDOM_STATE",
    "code_challenge": "BASE64URL_SHA256_OF_VERIFIER",
    "code_challenge_method": "S256",
    "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
    "client_assertion": "YOUR_CLIENT_ASSERTION_JWT"
  }'

Nimm billing:attribution offline_access als Scope, wenn du ein Refresh Token willst. Fügst du das später hinzu, muss der Kunde erneut zustimmen, und du ersetzt die gespeicherte Verbindung.

Schicke den Browser an https://auth.claude.com/oauth/authorize mit deiner client_id und der zurückgegebenen request_uri, die nach 10 Minuten abläuft. Wer zustimmt, braucht die Rolle Admin oder Billing in seiner Organisation. Prüfe im Callback zuerst state und behandle einen error-Parameter als fehlende Verknüpfung. Der Code ist nur einmal verwendbar und gilt 5 Minuten. Tausche ihn aus deinem Backend mit dem Verifier an /v1/oauth/token ein und speichere die Token-Werte sofort, denn sie werden nur einmal ausgegeben.

Sag den Nutzern, sie sollen prüfen, welches Claude-Konto die Zustimmungsseite anzeigt. Sie bietet nur die Organisationen dieses Kontos an, die gewählte Organisation zahlt, und die Token-Antwort verrät dir nicht, welche es war.

Wie legt billing_policy fest, wer einen Claude-Request bezahlt?

Mit deinem Operator-Credential belastet bill_to: "user_profile" den im Profil-Header genannten Kunden, bill_to: "self" oder ein fehlendes billing_policy belastet dich. Jeder Request mit billing_policy braucht den Beta-Header. $OPERATOR_TOKEN ist hier das Token des Service Accounts aus deiner Federation Rule, nicht ein Token aus dem Code-Austausch:

shell
curl https://api.anthropic.com/v1/messages \
  -H "Authorization: Bearer $OPERATOR_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"}
  }'

Für ein Per-Connection-Token gilt eine andere Regel. An diesen Endpunkten belastet es immer seinen eigenen Kunden. Lässt du billing_policy weg, wird der Request also nicht zu deinem, und bill_to: "self" gibt einen 400 zurück.

Das Python SDK 2.10.0 hat typisierte Parameter billing_policy und user_profile_id an client.beta.messages.create. In meinem Stub-Lauf haben sie den Header anthropic-beta nicht von selbst gesetzt, mit betas=[...] schon, gib ihn also mit. Der Versions-Header ist die API-Version 2026-10-21, die dieses SDK standardmäßig sendet.

Die Abdeckung ist kleiner als die Messages API insgesamt. billing_policy funktioniert an /v1/messages und /v1/chat/completions, /v1/messages/count_tokens akzeptiert und ignoriert es. Ein Batch-Eintrag, der auf den Kunden abgerechnet werden soll, kommt als errored zurück und niemand zahlt dafür, und kostenpflichtige Code-Execution-Features geben bei einem auf den Kunden abgerechneten Request einen 400 zurück. Markiere nur Nutzung, die der Kunde veranlasst hat: Deine Evals und Tests dürfen nicht als user_profile rausgehen, und die API kann das nicht für dich prüfen.

Was sollte deine App tun, wenn Claude Linked Billing einen Request ablehnt?

Die Ablehnung anzeigen und aufhören. Sende den Request nicht standardmäßig auf deine eigene Rechnung neu. Anthropics Regel für einen auf den Kunden abgerechneten Request ist kurz: Er landet nie stillschweigend auf deiner Rechnung.

It never silently bills you instead.

Diese Antworten musst du behandeln:

AntwortBedeutungWiederholen?
403 user_profile_not_billabledein Credential, ein nicht verknüpftes Profil, eine beendete Verknüpfung oder eine nicht berechtigte Organisation; die Antwort sagt nicht, was davonnein, außer in den ersten 10 Sekunden nach einer neuen Verknüpfung
402 linked_organization_spend_limit_reacheddas Limit deiner App, das Monatslimit der Organisation oder kein Guthaben, das zahlen kann; abgelehnt, bevor eine Antwort beginntnein
402 linked_organization_billing_unavailableAbrechnung gerade nicht möglich, etwa bei einer gesperrten Organisation oder wenn das Guthaben ausgeht, nachdem die Antwort begonnen hatnein
503 overloaded_errorAbrechnungsstatus konnte nicht bestätigt werden; nicht bedient, nicht berechnetja, mit Backoff und unter Beachtung von retry-after

An /v1/messages steht der Code in error.details.error_code. An /v1/chat/completions gibt es diesen Code nicht, dort verzweigst du anhand des HTTP-Status und von error.code, das den Fehlertyp enthält.

Für den 403 und beide 402er ergänzt die Doku, dass du mit bill_to: "self" neu senden kannst. Packst du das in einen generischen Fallback, hast du genau die stille Abrechnung nachgebaut, die Anthropic verweigert hat: Ein falsch konfiguriertes Credential erzeugt bei jedem Kunden denselben 403, und dein Code schiebt sie alle unbemerkt auf deine Rechnung. Einen 403 würde ich deshalb nie auf meine Rechnung nehmen, einen 402 nur, wenn das vorgelagert genehmigt wurde. Dieser Handler ist für Aufrufe ohne Streaming mit dem Operator-Credential gedacht:

python
import anthropic
 
BILLING_BETA = "user-profiles-billing-2026-10-01"
NOT_BILLABLE = (403, "user_profile_not_billable")
PAYMENT_REFUSED = {
    (402, "linked_organization_spend_limit_reached"),
    (402, "linked_organization_billing_unavailable"),
}
 
class BillingRefused(Exception):
    def __init__(self, code, request_id):
        super().__init__(f"{code} (request {request_id})")
        self.code = code
        self.request_id = request_id
 
def create(operator_client, profile_id, bill_to, **params):
    return operator_client.beta.messages.create(
        betas=[BILLING_BETA],
        user_profile_id=profile_id,
        billing_policy={"type": "billing_policy", "bill_to": bill_to},
        **params,
    )
 
def run_for_customer(operator_client, profile_id, you_approved_paying=False, **params):
    try:
        reply = create(operator_client, profile_id, "user_profile", **params)
        return reply, "customer"
    except anthropic.APIStatusError as exc:
        refusal = (exc.status_code, exc.error_code)
        if refusal != NOT_BILLABLE and refusal not in PAYMENT_REFUSED:
            raise
        if refusal == NOT_BILLABLE or not you_approved_paying:
            raise BillingRefused(exc.error_code, exc.request_id) from exc
    return create(operator_client, profile_id, "self", **params), "you"

Der Stub-Lauf, eine Zeile pro Fall, mit dem bill_to-Wert jedes Versuchs:

uprof_ok        -         ok, payer=customer                                      sent=['user_profile']
uprof_unlinked  -         BillingRefused user_profile_not_billable                sent=['user_profile']
uprof_capped    -         BillingRefused linked_organization_spend_limit_reached  sent=['user_profile']
uprof_suspended -         BillingRefused linked_organization_billing_unavailable  sent=['user_profile']
uprof_busy      -         ServiceUnavailableError 503                             sent=['user_profile', 'user_profile', 'user_profile']
uprof_typo      -         BadRequestError 400                                     sent=['user_profile']
uprof_unlinked  approved  BillingRefused user_profile_not_billable                sent=['user_profile']
uprof_capped    approved  ok, payer=you                                           sent=['user_profile', 'self']
uprof_suspended approved  ok, payer=you                                           sent=['user_profile', 'self']

Der 503 ging dreimal raus, weil zuerst die zwei Standard-Retries des SDK laufen und der Handler den letzten 503 dann weiterreicht. Der Aufrufer muss sich also trotzdem darum kümmern. you_approved_paying ist nur ein Flag. Soll dahinter ein Ausgabenlimit stehen, musst du diese Logik selbst bauen, und jeder übernommene Request gehört in deine Logs.

Zwei Einschränkungen gelten. Der erneute Versand braucht das Operator-Credential, denn ein Per-Connection-Token kann keinen Request senden, den du bezahlst. Und wenn das Guthaben ausgeht, nachdem eine Antwort begonnen hat, beschreibt die Linked-Billing-Doku weder, was ein Streaming-Client sieht, noch, was mit der Teilausgabe passiert. Ein erneuter Versand beginnt von vorn und geht auf deine Kosten.

Fang bei einem 403 auf deiner Seite an: Prüfe Credential, Profilzuordnung und Verknüpfung, bevor du den Kunden behelligst. Bei einer 402-Limit-Ablehnung schickst du den Kunden an drei Stellen in der Console, denn der Code sagt nicht, welche zutrifft: Linked platforms für das Limit deiner App, Spend limits für das Monatslimit der Organisation und Billing für das Guthaben. Eine Limit-Ablehnung gilt bis 00:00 UTC am Ersten des nächsten Monats, sofern das Limit nicht erhöht oder entfernt wird. Einer Organisation ohne Guthaben hilft der neue Monat allerdings nicht.

Wie verhinderst du, dass Claude Linked Billing den falschen Kunden belastet?

Nimm die Profil-ID aus deinem eigenen serverseitigen Mandantendatensatz, nie aus etwas, das der Client schickt. Standardmäßig kann dein Operator-Credential jeden verknüpften Kunden belasten. Die Doku nennt die Folge in einer Warnung: Nennt ein Request ein anderes verknüpftes Profil, zahlt dessen Organisation, und kein Fehler weist darauf hin.

If a request with that credential names a different profile linked through this app, Anthropic bills that profile’s organization, and no error tells you.

Die strukturelle Lösung ist ein Per-Connection-Access-Token, das nur seinen eigenen Kunden belasten kann und ein anderes Profil mit einem 400 ablehnt. Während der Beta musst du allerdings dein Anthropic-Account-Team fragen, ob diese Tokens für deine Organisation aktiviert sind, und dasselbe gilt für die Einstellung, die dem Operator-Credential das Belasten von Kunden ganz verbietet. Plane nicht damit, bevor du die Antwort hast. Stelle vor dem Einschalten dieser Einstellung sicher, dass das Token jedes Kunden funktioniert, sonst bekommen verknüpfte Kunden 403er.

Bekommst du diese Tokens, sind die Refresh-Regeln streng. Access Tokens halten höchstens eine Stunde, Refresh Tokens höchstens ein Jahr, und ein Refresh verlängert dieses Jahr nicht. Kommt ein benutztes Refresh Token mehr als 30 Sekunden nach der ersten Verwendung noch einmal an, endet die Verbindung, alle Tokens werden widerrufen und der Kunde ist nicht mehr verknüpft. Stoße den Refresh also aus einem einzigen Dienst an, immer nur einen gleichzeitig, mit einem über alle Replikas geteilten Lock, und schalte automatische Retries in deinem HTTP-Client und in jedem Proxy ab. Speichere das neue Paar, bevor du es benutzt. Der schwierige Fall ist eine verlorene Antwort: Der Guide führt genau auf, wann ein einmaliger sofortiger erneuter Versand erlaubt ist und wann du aufhören und neu verknüpfen musst, setze diese Liste also wortgetreu um. Ruft eine Agent-Sandbox die API auf, gib ihr das Access Token und lass das Refresh Token auf dem Server.

Wie verfolgst du, wer die Nutzung von Claude Linked Billing bezahlt hat?

Führe ein eigenes Ledger, denn eine erfolgreiche Antwort sagt nicht, wer belastet wurde. Halte für jeden Versuch Profil, Credential-Typ, bill_to-Wert und request-id fest.

Anthropics Reporting taugt nur zur groben Kontrolle, und es braucht ein Admin-API-Credential, nicht deinen Operator Service Account. Am Kosten-Endpunkt der Usage and Cost Analytics API, gruppiert nach user_profile_id, trägt ein vom Kunden bezahlter Request 0 zu amount und seinen Listenpreis zu list_amount bei. Ein Feld oder einen Filter für den Zahler gibt es nicht, und laut Doku bedeutet eine Zeile mit amount 0 und list_amount über 0 meist, dass der Kunde alles bezahlt hat. Ein steigender amount bei einem verknüpften Profil ist einen Alarm wert, denn dort würden übernommene Requests auftauchen, und dein Ledger sagt dir, ob sie übernommen wurden oder einfach deine waren. Die Daten werden meist innerhalb von 4 Stunden aktualisiert und können bis zu 24 brauchen, setze Limits also nicht darüber durch.

Du bekommst auch kein Signal, wenn ein Kunde geht. Beim Lösen der Verknüpfung gibt es weder Webhook noch E-Mail. Das erste Anzeichen ist ein abgelehnter Request, es sei denn, du fragst das Profil regelmäßig ab:

shell
curl "https://api.anthropic.com/v1/user_profiles/uprof_01HV9Z?oauth_app_id=YOUR_CLIENT_ID" \
  -H "Authorization: Bearer $OPERATOR_TOKEN" \
  -H "anthropic-version: 2026-10-21" \
  -H "anthropic-beta: user-profiles-search-2026-08-30"

connection_status.type lautet connected, disconnected oder not_connected. Behandle null oder einen unerwarteten Wert als unbekannt, und denk daran, dass connected nicht verspricht, dass der nächste Request abgerechnet werden kann.

Was solltest du prüfen, bevor du Claude Linked Billing auslieferst?

Prüfe vier Dinge: dass kein betroffener Kunde eigene ZDR-, BAA-, HIPAA-, FERPA- oder CMEK-Bedingungen braucht, dass deine Rate Limits den gemeinsamen Traffic tragen, dass die Profil-ID nicht vom Client kommen kann und dass kein Codepfad eine Ablehnung ohne ausdrückliche Genehmigung in bill_to: "self" verwandelt. Hol dir dann von deinem Account-Team die Antwort zu den Per-Connection-Tokens. Das hier ist eine Beta, und Anthropic sagt, dass sich Endpunkte, Parameter und Verhalten ändern können, halte den Abrechnungscode also in einem Modul, das du neu schreiben kannst.

01 / Diskussion

Hier gibt es keine Kommentarspalte. Diskussionen laufen auf X.

Max Nardit@mnardit

02 / Weitere Artikel