Max Nardit
← 記事
15 mindev

Claude linked billing: billing_policy で顧客に支払いを移しても、リクエストは自社の組織で動く

403 を一度読み違えるだけで全テナントの費用が自社の請求に移ることがあり、ヘッダーを一つ間違えると別の顧客に課金されます。こうした失敗が潜む場所と、最初に記録すべきものをまとめました。

目次

Anthropic が 2026 年 11 月 17 日にベータ公開した Claude linked billing を使うと、顧客は自分の Claude 組織をあなたのアプリに連携し、そこで発生した Claude の利用料を自分で支払えます。移るのは請求だけです。リクエストはあなたの組織で実行され、レート制限もモデルへのアクセス権もデータ保持の条件もあなたのものが適用されます。支払い元の保証も、見た目より簡単に失われます。Anthropic は顧客請求のリクエストをあなたに課金する代わりに拒否しますが、ドキュメントはその続きで bill_to: "self" で再送できると説明しています。この再送を汎用のフォールバックに入れると、認証情報の設定ミス一つで全顧客の費用があなたの請求に移り、エラーはどこにも出ません。

実際のフローは試していません。登録済みの OAuth アプリ、Workload Identity Federation、条件を満たす 2 つ目の組織が必要だからです。以下のプロトコルの詳細は、11 月 19 日時点の Anthropic のドキュメントに基づきます。エラーハンドラーは実際に動かしたコードですが、Python SDK 2.10.0 から、ドキュメント記載のエラーを返すローカルのスタブに対して実行したものです。わかるのはこのコードの挙動だけで、Anthropic のサーバーの挙動はわかりません。推奨事項は筆者の解釈です。

Claude linked billing で顧客に移るものは何か

請求だけで、ほかはほとんど移りません。Anthropic はあなたが指定したリクエストの料金を顧客の組織に請求し、顧客はあなたのアプリに月額の利用上限を設定したり、連携を解除したりできます。リクエストの処理に関わるものはあなたの側に残ります。

顧客請求のリクエストでの帰属先
請求顧客の組織
アプリに対する月額利用上限 (任意)顧客。あなたは読み取れません
レート制限、モデルへのアクセス権、サービスティアあなた
データ保持と暗号鍵あなた
顧客の ZDR、BAA、CMEK適用されません

最後の行は、営業とセキュリティの担当者に真っ先に見せるべきものです。自社の組織で Zero Data Retention を契約している顧客は、それが請求についてくると考えるかもしれません。そうはならず、ドキュメントもこの利用に HIPAA、FERPA、CMEK の対応が必要な顧客は連携しないよう求めています。

Claude linked billing を利用できる組織の条件

双方が Anthropic に直接支払っている必要があります。あなたの組織がそうでなければ、顧客請求のリクエストはエラーコードのない 403 で失敗します。顧客の組織は、API 利用料をプリペイドのクレジットか請求書払いで支払っていなければなりません。AWS、Google Cloud、Azure のマーケットプレイス経由で請求される組織は対象外で、Claude のサブスクリプションプランしか持たない組織も同様です。これらの組織のリクエストには 403 user_profile_not_billable が返ります。

クレジットの種類も重要です。Console で購入したクレジットは支払いに使えます。Max、Ultra、Team プランに付く月次の API クレジットは使えないため、これらのプランで受け取った残高は充当されません。Anthropic のパートナー、VC、スタートアップ向けプログラムのクレジットも同じです。

これらの条件が整っていなくても、連携自体は完了することがあります。Anthropic 自身が、成功メッセージは「請求が有効」ではなく「連携済み」とするよう勧めており、UI でもこの助言は文字どおりに受け取るべきだと考えます。

Claude linked billing は顧客の API キーを預かるより優れているか

Console アカウントを持ち、特別なデータ条件のない顧客なら、優れていると考えます。顧客の API キーを保持せずに済み、顧客は上限と解除の手段を自分で管理できます。代償はレート制限の余裕です。連携した顧客は全員あなたの枠を消費するので、利用の多いテナントが共有の枠を使い切ると、別のテナントに 429 が返ります。

顧客自身のキーを使う場合、リクエストは顧客の組織に送られます。ZDR は組織単位で有効化されるため、顧客が独自のデータ条件を必要とするならこちらを検討することになります。ただしキーだけでは決まらず、ワークスペースの設定、モデル、使用する機能がすべて関わります。linked billing のガイドは両者を比較していないので、規制対象の顧客については Anthropic に確認してください。この利用に HIPAA、FERPA、CMEK の対応が必要な顧客には、linked billing を提供しないでください。

Claude linked billing 用の OAuth アプリを登録する方法

linked billing のガイドによると、登録は一度だけで、Claude 組織の Admin ロールが必要です。

  1. Console の OAuth apps でアプリを作成し、リダイレクト URI を設定して Bill and link to organizations を選びます。
  2. Client authentication で ID プロバイダーと subject パターンを登録します。Anthropic はクライアントシークレットを発行しないので、バックエンドはそのプロバイダーの JWT で自身を証明します。
  3. フェデレーションルール付きのサービスアカウントを作成し、アプリの operator サービスアカウントに指定します。バックエンドはこの ID で Claude を呼び出します。
  4. そのサービスアカウントが所属するデフォルトのワークスペースを選びます。これがないと、接続単位トークン (顧客 1 社の連携に紐づくアクセストークン。後述) を使わない場合でも、コード交換が unauthorized_client で失敗します。
  5. 接続単位トークンのリフレッシュトークンを受け取るには、顧客が承認する前に Permissions タブで Offline access を有効にします。
  6. テストでは、条件を満たす別の組織の担当者を Test users に追加します。アプリを所有する組織は連携できず、テスト中の上限は月 50 ドルまでです。
  7. 公開します。請求書払いなら確認の時点で公開されます。それ以外は、検証済みドメインでカバーされていない限り DNS の TXT レコードでドメインを証明し、Anthropic の審査を受けます。DNS の反映には最大 48 時間かかることがあります。

プロファイルの対応付けは、最初の連携より前に決めてください。1 つのアプリ内で、顧客の組織はあなたのユーザープロファイル 1 つだけに連携し、プロファイルも 1 つの組織にしか連携しません。すでに個人ごとにプロファイルを持っているなら、Anthropic は顧客の組織用にもう 1 つプロファイルを作って連携することを勧めています。

顧客の組織を Claude OAuth アプリに連携する方法

ユーザープロファイルを作成し、Pushed Authorization Request を送り、ユーザーをリダイレクトして、コードを交換します。プロファイルを 2 回作成すると、reference_id が同じでも 2 つできるので、ID は保存してください。リクエストの前に新しい state と 43〜128 文字の PKCE verifier を生成し、どちらもブラウザーセッションと顧客レコードに紐づけて保存します。

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"
  }'

リフレッシュトークンが必要なら、スコープに billing:attribution offline_access を指定します。後から追加すると、顧客の再承認と保存済み接続の置き換えが必要になります。

ブラウザーを client_id と返された request_uri を付けて https://auth.claude.com/oauth/authorize に送ります。request_uri の有効期限は 10 分です。承認者には、自分の組織の Admin または Billing ロールが必要です。コールバックではまず state を確認し、error パラメーターがあれば連携なしとして扱います。コードは 1 回限りで、有効期限は 5 分です。バックエンドから verifier とともに /v1/oauth/token で交換し、トークンの値はすぐに保存してください。返されるのは一度だけです。

承認画面にどの Claude アカウントが表示されているか、ユーザーに確認してもらってください。画面にはそのアカウントの組織しか出ず、選んだ組織が支払い元になり、トークンのレスポンスからはどの組織が選ばれたのかわかりません。

Claude のリクエストの支払い元を billing_policy で決める方法

operator の認証情報では、bill_to: "user_profile" はプロファイルヘッダーで指定した顧客に請求し、bill_to: "self" または billing_policy なしの場合はあなたに請求します。billing_policy を指定するリクエストにはベータヘッダーが必要です。ここでの $OPERATOR_TOKEN はフェデレーションルールで得たサービスアカウントのトークンで、コード交換で得たトークンではありません。

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"}
  }'

接続単位トークンのルールは異なります。billing_policy に対応するエンドポイントでは常に紐づいた顧客に請求するので、billing_policy を省いてもあなたの負担にはならず、bill_to: "self" は 400 を返します。

Python SDK 2.10.0 の client.beta.messages.create には、型付きの billing_policy と user_profile_id パラメーターがあります。スタブでの実行では、これらだけでは anthropic-beta ヘッダーは付かず、betas=[...] を渡すと付いたので、指定してください。バージョンヘッダーは API バージョン 2026-10-21 で、この SDK がデフォルトで送信します。

対応範囲は Messages API 全体より狭くなっています。billing_policy が機能するのは /v1/messages と /v1/chat/completions で、/v1/messages/count_tokens は受け付けますが無視します。顧客請求を指定したバッチの項目は errored で返り、誰にも課金されません。課金対象のコード実行機能は、顧客請求のリクエストでは 400 を返します。顧客の指示による利用だけを指定してください。自社の評価やテストを user_profile で送ってはいけませんし、API はそれを検出できません。

Claude linked billing がリクエストを拒否したときのアプリの対応

拒否を表示して止めます。デフォルトで自社負担に切り替えて再送してはいけません。顧客請求のリクエストに関する Anthropic のルールは短く、顧客に請求できなくても、黙って代わりにあなたに請求することはない、というものです。

It never silently bills you instead.

処理すべきレスポンスは次のとおりです。

レスポンス意味再試行
403 user_profile_not_billable認証情報、未連携のプロファイル、終了した連携、対象外の組織のいずれか。どれかはレスポンスからわかりませんしない。新規連携から 10 秒以内は例外
402 linked_organization_spend_limit_reachedアプリの上限、組織の月額上限、または支払いに使えるクレジットがない状態。応答の開始前に拒否されますしない
402 linked_organization_billing_unavailable現在請求できない状態。組織の停止や、応答の開始後にクレジットが尽きた場合などしない
503 overloaded_error請求状態を確認できませんでした。処理も課金もされていませんする。バックオフし、retry-after に従います

/v1/messages では、コードは error.details.error_code に入ります。/v1/chat/completions にはこのコードがないので、HTTP ステータスと、エラー種別が入る error.code で分岐します。

403 と 2 種類の 402 について、ドキュメントは bill_to: "self" で再送できると補足しています。これを汎用のフォールバックに包むと、Anthropic があえて拒否した「黙って請求する」動作を自分で作り直すことになります。認証情報の設定ミスは全顧客に同じ 403 を返し、コードが全員分を黙ってあなたの請求に移すからです。そのため、403 は決して肩代わりせず、402 は上流で承認があるときだけ肩代わりする方針を取ります。次のハンドラーは、operator の認証情報を使う非ストリーミング呼び出し用です。

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"

スタブでの実行結果です。1 行が 1 ケースで、各試行で送った bill_to を示しています。

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']

503 のケースでリクエストが 3 回送られているのは、まず SDK のデフォルトの 2 回の再試行が走り、その後ハンドラーが最後の 503 をそのまま上に渡すためです。呼び出し側での対処は依然として必要です。you_approved_paying は単なるフラグです。支出の上限を設けたいなら、そのロジックは自分で作る必要があり、肩代わりしたリクエストはすべてログに残すべきです。

制約が 2 つあります。接続単位トークンではあなたの負担になるリクエストを送れないので、再送には operator の認証情報が必要です。また、応答の開始後にクレジットが尽きた場合にストリーミングのクライアントに何が見えるのか、途中までの出力がどうなるのかは、linked billing のドキュメントに書かれていません。再送は最初からやり直しとなり、費用はあなたの負担です。

403 の調査は自社側から始めます。顧客に連絡する前に、認証情報、プロファイルの対応付け、連携の状態を確認してください。上限による 402 の場合は、コードからはどれが該当するかわからないので、顧客に Console の 3 か所を案内します。アプリの上限は Linked platforms、組織の月額上限は Spend limits、クレジットは Billing です。上限による拒否は、上限を引き上げるか削除しない限り、翌月 1 日の 00:00 UTC まで続きます。ただし、クレジットが尽きた組織は月が替わっても解決しません。

Claude linked billing で別の顧客への誤請求を防ぐ方法

プロファイル ID は自社サーバー側のテナントレコードから取得し、クライアントから送られた値は決して使わないでください。デフォルトでは、operator の認証情報は連携済みのどの顧客にも請求できます。ドキュメントは警告の中で、別の連携済みプロファイルを指定すると、エラーなしでそのプロファイルの組織に請求されると述べています。

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.

根本的な対策は接続単位のアクセストークンです。紐づいた顧客にしか請求できず、別のプロファイルは 400 で拒否します。ただしベータ期間中は、このトークンが自社の組織で有効かどうかを Anthropic のアカウントチームに確認する必要があり、operator の認証情報による顧客請求を完全に止める設定についても同様です。回答を得るまでは、これらを前提に計画しないでください。この設定を有効にする前に、全顧客のトークンが動作することを確認してください。そうしないと、連携済みの顧客に 403 が返り始めます。

トークンを使えるようになっても、リフレッシュのルールは厳格です。アクセストークンの有効期間は最長 1 時間、リフレッシュトークンは最長 1 年で、リフレッシュしてもこの 1 年は延びません。使用済みのリフレッシュトークンが最初の使用から 30 秒を超えて再び届くと、接続は終了し、すべてのトークンが失効して顧客の連携が解除されます。リフレッシュは 1 つのサービスから一度に 1 件ずつ、レプリカ間で共有するロックのもとで行い、HTTP クライアントとプロキシの自動再試行は無効にしてください。新しいトークンの組は使う前に保存します。難しいのはレスポンスが失われた場合です。すぐの再送が 1 回だけ許される条件と、中止して再連携すべき条件はガイドに列挙されているので、そのとおりに実装してください。エージェントのサンドボックスから API を呼ぶなら、渡すのはアクセストークンだけにして、リフレッシュトークンはサーバーに置きます。

Claude linked billing の利用料を誰が払ったか追跡する方法

成功レスポンスからは請求先がわからないので、独自の台帳を持ちます。試行ごとに、プロファイル、認証情報の種類、bill_to の値、request-id を記録してください。

Anthropic のレポートは大まかな確認にしか使えず、operator のサービスアカウントではなく Admin API の認証情報が必要です。Usage and Cost Analytics API のコストエンドポイントを user_profile_id でグループ化すると、顧客が支払ったリクエストは amount に 0、list_amount に定価を加算します。支払い元を示すフィールドやフィルターはなく、ドキュメントによれば amount が 0 で list_amount が 0 より大きい行は、通常は顧客が全額を支払ったことを意味します。連携済みプロファイルで amount が増えていたらアラートを出す価値があります。肩代わりしたリクエストはそこに現れるからで、肩代わりなのか単に自社の利用なのかは台帳で判断できます。データは通常 4 時間以内に更新されますが、最大 24 時間かかることがあるので、上限の強制には使わないでください。

顧客が離れたときの通知もありません。連携解除では Webhook もメールも届きません。プロファイルをポーリングしない限り、最初の兆候はリクエストの拒否です。

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 は connected、disconnected、not_connected のいずれかです。null や未知の値は不明として扱ってください。また、connected は次のリクエストの請求成功を保証するものではありません。

Claude linked billing のリリース前に確認すべきこと

確認するのは 4 点です。対象の顧客の中に独自の ZDR、BAA、HIPAA、FERPA、CMEK の条件を必要とする顧客がいないこと。レート制限が全顧客の合計トラフィックに耐えられること。プロファイル ID がクライアントから来ないこと。明示的な承認なしに拒否を bill_to: "self" に変えるコードパスがないこと。そのうえで、接続単位トークンについてアカウントチームの回答を得てください。これはベータ版で、Anthropic はエンドポイント、パラメーター、動作が変わる可能性があるとしています。請求関連のコードは、書き直しやすいよう 1 つのモジュールにまとめておきましょう。

01 / ディスカッション

コメント欄はありません。議論は X で行っています。

Max Nardit@mnardit

02 / ほかの記事

  1. Gemini 4 Carbon のタスクあたりコスト:Google の「2X」を12月の価格でリーダーボードごとに検証

    Zapier は Carbon を定価で計算しているので、2X がそのまま成り立ちます。CursorBench と Agent Arena は導入価格で計算しているので、12月1日に倍率はおよそ半分になります。Google が 6X とする MKA の差は、Artificial Analysis 自身の数字では 5X です。数時間におよぶ実行のコストを示す数字は、どれにもありません。

  2. Messages API の Claude メッセージスレッド:スレッドが省くのはアップロード、プレフィルを省けるのはキャッシュだけ

    TTFT 35% 短縮という数字は本物ですが、対象は 50 万トークン以上の Claude Code のトラフィックに限られます。スレッドとプロンプトキャッシュは別々のコストを、別々のタイマーで削ります。1 時間キャッシュでは、先に期限が切れるのはスレッドの方です。

  3. ChatGPT と Codex の利用上限が 12 月から共通に:Codex がすでに使っている枠にチャットが加わる

    Codex はすでに ChatGPT の Work と利用枠を共有しています。12 月に加わるのはチャットで、メッセージ数ではなくトークンで数えられ、Instant チャットは対象外です。チャットのモデル別メッセージ上限が残るのか、共通の枠がどれだけの大きさなのかを OpenAI は明らかにしていません。