# Linked billingでエンドカスタマーに課金する設計

> Claude APIのLinked billingは、顧客自身のClaude組織に利用料を請求する仕組みです。billing_policy、接続トークン、リフレッシュ運用の設計判断をまとめます。

- Canonical: https://kuucorp.com/blog/claude-linked-billing-billing-policy-connection-token-design/
- Date: 2026-11-20
- Last modified: 2026-11-20
- Publisher: Kuu株式会社 (https://kuucorp.com)

---
自社プロダクトや社内基盤に Claude を組み込み、利用料を顧客や関連会社へ按分している場合、トークン単価の転嫁と請求書発行は自前の仕事になります。2026年11月17日にベータで提供が始まった Linked billing は、顧客が自分の Claude 組織で利用料を直接支払う仕組みです。課金主体をリクエスト単位で切り替えられる反面、認証情報の持ち方を誤ると他社へ課金する事故が起きます。

ユーザープロファイル単位の帰属と制限の閉じ込めは[Claude APIユーザープロファイルの設計と統制](/blog/claude-user-profiles-end-customer-attribution-enforcement-design/)、利用量の集計は[Usage and Cost Analytics APIの移行と帰属設計](/blog/claude-usage-cost-analytics-api-migration-attribution-design/)も参照してください。

## Linked billingとは何か

> Linked billing は、顧客が自社のClaude組織を一度リンクし、リクエストごとに支払い主体を選べるベータ機能です。ヘッダーは user-profiles-billing-2026-10-01 です。

顧客は OAuth で自分の組織をアプリにリンクします。このリンクが接続（`ocon_` 始まりのID）です。各リクエストに `billing_policy` を付け、`bill_to: "user_profile"` なら顧客、`"self"` または未指定なら自社が支払います。顧客に請求できないリクエストは拒否され、自社請求へ黙って切り替わることはありません。

対象は Anthropic へ直接支払う組織（前払いクレジットか請求書払い）です。AWS・Google Cloud・Azure のマーケットプレイス経由や、サブスクリプションのみの組織は `403 user_profile_not_billable` になります。対応エンドポイントは `/v1/messages` と `/v1/chat/completions` です。Message Batches は顧客課金に非対応で、該当項目は `errored` になり、誰にも請求されません。

## どこで実行され、どの契約条件が効くのか

> リクエストは自社組織で実行されます。レート制限・モデル権限・データ保持は自社側が適用され、顧客のZDR・BAA・CMEKは効きません。

支払いだけが顧客に移ります。HIPAA、FERPA、CMEK の適用が必要な顧客は、この方式でリンクしてはいけません。自社が課金済みの特別なクレジット（Max・Ultra・Team プランの月次クレジット、パートナーやスタートアップ向けクレジット）は充当されません。支払い手段が無いと `402` が返りますが、原因がクレジット不足か上限到達かは区別できません。

課金できないコードは `/v1/messages` の課金対象コード実行です。顧客課金のリクエストでは `400` になるため、`bill_to: "self"` で送ります。

## 認証と接続トークンをどう設計するか

> 自社バックエンドは private_key_jwt 形式のクライアントアサーションで認証し、アクセストークンは1時間以内、リフレッシュトークンは最長1年です。

Anthropic はクライアントシークレットを発行しません。バックエンドは IdP から得た署名付きアサーション（RFC 7523）で PAR、トークン、失効の各エンドポイントを呼びます。リンクは PAR（有効600秒）→ 認可画面（Admin か Billing ロールが承認）→ コード交換（単一使用、5分）の順で、トークンは返却時の1回しか取得できません。

支払い先の取り違えを防ぐ方法が2つあります。

1. **接続トークン**: 特定の顧客だけに課金できるトークンです。既定のサービスアカウント認証では、ヘッダーで別のリンク済みプロファイルを指すと、エラーなくその顧客に課金されます
2. **`disable_operator_only_auth`**: 全リクエストに接続トークンを強制します。アカウントチームの承認が要り、サービスアカウント単独の顧客課金は `403` になります

リフレッシュは更新のたびにトークンが置き換わります。同じ接続で直列化し、新しいトークンを保存してから使います。30秒を超えて旧トークンを再利用すると接続が終了し、顧客は **Unlinked** になります。HTTP の自動再試行は無効にしてください。サンドボックスにはアクセストークンだけを渡し、リフレッシュトークンはバックエンドに置きます。

## 運用で何を監視し、何を制限するか

> 接続が connected でも課金成功は保証されません。顧客支払いのリクエストは自社の支出に加算されず、集計は約1時間遅れるため、実時間の上限制御には使えません。

状態は `GET /v1/user_profiles/{id}?oauth_app_id=...`（`user-profiles-search-2026-08-30` ヘッダー）で `connected`・`disconnected`・`not_connected` として取得できます。Admin API の使用量・費用は `user_profile_id` でグループ化でき、顧客払いの行は `amount` が0で `list_amount` が正の値になります。「誰が払ったか」のフィルターはありません。

自社のテストや評価、他の顧客の作業に `user_profile` を付けないでください。API は検証できません。ゲートウェイ側で、ヘッダーのプロファイルIDと呼び出し元テナントを突き合わせる検査を入れます。

## 参考

- [Linked billing — Claude Platform Docs](https://platform.claude.com/docs/en/manage-claude/oauth-apps/organization-billing-connections)
- [Claude Platform release notes — Claude Platform Docs](https://platform.claude.com/docs/en/release-notes/overview)
- [Offer linked billing in your platform — Claude Help Center](https://support.claude.com/en/articles/18467110-offer-linked-billing-in-your-platform)

## まとめ

Linked billing は、課金主体を接続単位で顧客に移し、請求の按分作業をなくします。ただし実行環境と契約条件は自社側に残ります。顧客ごとの接続トークンを使い、リフレッシュを直列化し、プロファイルIDとテナントの突き合わせをゲートウェイに置いてください。マルチテナントのClaude基盤設計は、[Kuuの大規模AI変革プログラム（RDE）](https://kuucorp.com/services/rde/)までご相談ください。
