본문으로 건너뛰기
블로그로 돌아가기
AI

클로드 API 결제를 고객에게 넘기려면? Linked billing 조건

클로드 Linked billing은 2026년 11월 17일 베타로 시작됐다. 앱을 쓰는 고객이 자기 클로드 조직 크레딧으로 사용료를 내는 방식, billing_policy 설정, 지출 한도와 오류 코드를 정리했다.

7분 소요AI
클로드 Linked billing클로드 API 결제클로드 플랫폼 릴리스 노트billing_policyAnthropic
클로드 API 결제를 고객에게 넘기려면? Linked billing 조건

클로드 API 결제를 고객에게 넘기려면 2026년 11월 17일 베타로 시작된 Linked billing(연결 결제)을 쓴다. 고객이 앱에서 자기 Claude 조직을 한 번 연결해 두면, 앱이 요청마다 billing_policy로 고객과 운영자 중 누가 낼지 고르고, 고객이 내는 요청은 그 조직의 크레딧에서 빠진다. 조건은 고객 조직이 API 사용료를 Anthropic에 직접 낸다는 것이다. Claude Platform 릴리스 노트가 이 기능을 공개했고, 지금까지 앱 운영자가 전부 떠안던 API 비용을 사용량이 많은 고객에게 나눌 수 있다. 앱을 쓰기만 하는 사람은 앱이 "Claude 조직 연결" 화면을 보여 줄 때 무엇을 승인하는지만 알면 된다.

Anthropic이 2026년 11월 17일 Claude Platform에 Linked billing을 베타로 열었고, 사용하려면 요청에 user-profiles-billing-2026-10-01 베타 헤더가 필요하다.

고객은 앱을 한 번 연결해 두면 앱이 요청마다 정하는 대로 자기 조직 크레딧에서 사용료가 빠지고, 연결할 때 앱 전용 월 지출 한도를 직접 정한다.

API 사용료를 Anthropic에 직접 내는 조직만 연결할 수 있어서, Claude 구독(프로·맥스)만 쓰는 사람이나 AWS·구글 클라우드·Azure로 결제하는 조직은 해당되지 않는다.

클로드 Linked billing으로 누가 얼마를 내나

공식 문서에 따르면 고객은 앱에서 OAuth(다른 서비스에 로그인해 권한을 승인하는 표준 방식)로 자기 Claude 조직을 한 번 연결한다. 이 연결을 API에서는 connection이라 부른다. 연결된 뒤에는 앱이 요청마다 고객이 낼지 앱 운영자가 낼지 정하고, 고객이 낼 요청을 처리할 수 없으면 API는 요청을 거절할 뿐 운영자에게 대신 청구하지 않는다고 문서는 밝힌다. 고객은 언제든 연결을 끊을 수 있다.

구분내용
발표2026년 11월 17일 릴리스 노트(베타)
베타 헤더user-profiles-billing-2026-10-01
설정 위치/v1/messages, /v1/chat/completions 요청의 billing_policy
고객이 쓰는 화면Claude Console의 Linked platforms 페이지(지출 한도, 연결 해제)
지원하지 않는 것메시지 배치(/v1/messages/batches)

문서는 Claude Platform OAuth가 베타 서비스라서 엔드포인트와 동작이 바뀔 수 있고 운영 환경에 맞지 않을 수 있다고 밝힌다. 앱 개발사가 쓰는 사람이라면 시험용 조직으로 먼저 돌려 본 뒤 고객에게 열어야 한다.

연결 결제를 쓸 수 있는 고객 조건

문서가 정한 대상은 프리페이드 크레딧(미리 충전)이나 청구서 결제로 API 사용료를 Anthropic에 직접 내는 조직이다. 아래에 해당하면 요청이 403 user_profile_not_billable로 거절된다(대상 고객과 엔드포인트).

고객 상황연결 결제
Console에서 크레딧을 사거나 청구서로 결제하는 조직가능
AWS, 구글 클라우드, Azure를 거쳐 결제하는 조직불가
Claude 구독 요금제만 쓰는 조직불가

구글 클라우드 안에서 클로드를 쓰는 조직은 결제가 구글 쪽으로 잡히므로 대상이 아니다. 이 구조는 구글 클라우드 클로드 Anthropic 관리형 정식 출시 글에서 Google 관리형과 Anthropic 관리형의 결제 차이로 따로 정리했다.

크레딧도 모두 쓸 수 있는 것은 아니다. 문서에 따르면 Claude 맥스·울트라·팀 요금제에 딸린 월 API 크레딧과 Anthropic 파트너·VC·스타트업 프로그램 크레딧 일부는 이 결제에 쓸 수 없다. 쓸 수 있는 크레딧이 없으면 402가 돌아오는데, 응답만으로는 크레딧이 모자란 것인지 한도에 걸린 것인지 알 수 없다. 구독료와 API 사용료는 따로 쌓이므로 클로드 요금제를 이미 쓰는 사람도 API 크레딧이 있어야 앱 비용을 낼 수 있다. 요금제 자체가 궁금하면 클로드 요금제 비교에서 확인한다.

연결 승인은 Admin 또는 Billing 역할을 가진 사람만 할 수 있다. 개인 계정으로 접속하면 고를 조직이 없을 수 있고, 브라우저에 로그인된 계정의 조직만 목록에 나온다.

데이터 조건도 다르다. 문서에 따르면 연결 결제 요청은 앱 운영자의 조직에서 실행되어 운영자의 한도·모델 접근·서비스 등급·데이터 보관·암호화 키가 적용되고, 고객 조직의 ZDR(데이터 보관 안 함), BAA(의료정보 계약), CMEK(고객 관리형 암호화 키)는 적용되지 않는다. 의료·교육 기록처럼 이런 보호가 필요한 고객은 이 방식으로 연결하지 말라고 문서가 안내한다.

고객 연결부터 첫 요청까지 순서

앱 운영자는 Console의 OAuth apps 화면에서 앱을 만들고 Bill and link to organizations를 고른 뒤, 서비스 계정을 연결자(operator)로 지정한다. 이 준비는 앱당 한 번이고, 아래는 고객마다 반복하는 부분이다.

  1. 고객 한 명(Claude 조직 한 개)당 사용자 프로필(uprof_...)을 POST /v1/user_profiles로 만든다. 한 조직과 한 프로필은 일대일이다.
  2. 고객이 "Claude 조직 연결" 버튼을 누르면 백엔드가 https://auth.claude.com/v1/oauth/par로 승인 요청을 보내 request_uri를 받는다. 이 값은 600초 뒤 만료된다. 범위(scope)는 billing:attribution이다.
  3. 고객을 승인 페이지로 보낸다. 고객은 Claude에 로그인해 조직을 고르고, 결제 방식을 읽고, 월 지출 한도를 넣은 뒤 Link and authorize를 누른다.
  4. 돌아온 code와 state를 확인하고 토큰 엔드포인트에서 교환해 connection_id(ocon_...)를 받아 고객 기록에 저장한다. 코드는 한 번만 쓸 수 있고 5분 뒤 만료된다.
클로드 API 결제 Linked billing 연결 순서: 앱 등록, 고객 프로필, 연결 승인, billing_policy 요청, 지출 한도 확인
Linked billing 설정과 고객 연결의 큰 흐름

아래 그림은 공식 문서가 보여 주는 같은 흐름이다. 브라우저, 앱 백엔드, auth.claude.com 사이에서 5번(승인 요청), 6번(승인 페이지로 이동), 7번(고객 승인), 8번(토큰 교환) 순서로 오간다.

클로드 API 결제 Linked billing 고객 연결 시퀀스: 브라우저, 앱 백엔드, auth.claude.com 사이의 승인 요청과 토큰 교환
그림 1. 고객 연결 흐름. 출처: Anthropic 공식 문서 캡처(2026년 11월 18일)

운영에 열기 전에 직접 해 볼 수 있는 점검이 있다. 앱을 소유하지 않은 두 번째 조직(시험용)에 소액 크레딧을 넣고, 앱의 Test users에 그 조직의 Admin을 올려 연결한 뒤, 같은 질문을 bill_to: "user_profile"과 bill_to: "self"로 한 번씩 보낸다. 시험 조직의 Console 사용량에는 앞의 요청만, 운영 조직의 사용량에는 뒤의 요청만 쌓이는지 보면 설정이 맞는 것이다. 이 방법은 공식 문서의 시험 절차와 사용량 보고 설명을 따른 것이고, 필자가 이 기능을 직접 돌려 본 결과는 아니다.

연결에 성공해도 결제가 된다는 보장은 아니다. 문서는 화면에 "결제 활성"이 아니라 "연결됨"이라고 쓰라고 안내한다. 새 연결은 보통 곧바로 쓸 수 있지만 토큰 교환 뒤 약 10초 동안은 user_profile_not_billable이 날 수 있어서, 그 사이에는 다시 보내면 된다. 앱을 공개하기 전에는 앱의 Test users 목록에 있는 사람만 연결을 승인할 수 있고, 앱을 소유한 조직 자신은 연결 대상이 아니라서 시험하려면 별도의 두 번째 조직이 필요하다.

billing_policy로 요청마다 결제자 정하기

연결된 고객의 요청에는 anthropic-user-profile-id 헤더로 고객 프로필을 알리고, 고객이 내게 하려면 베타 헤더와 billing_policy 필드를 함께 보낸다.

"billing_policy": {"type": "billing_policy", "bill_to": "user_profile"}
설정결제자
bill_to: "user_profile"연결된 고객
bill_to: "self"앱 운영자
필드 없음앱 운영자(베타 헤더도 선택)
클로드 API 결제 Linked billing billing_policy 설정: user_profile은 고객 조직, self는 앱 운영자가 결제
billing_policy 값에 따른 결제자

문서는 고객이 직접 시킨 사용(앱 안에서 그 고객의 사용자가 일으킨 요청)에만 user_profile을 쓰라고 한다. 운영자 본인의 테스트, 평가, 다른 고객 작업에 붙이면 안 되고, API는 이를 검증하지 못한다. 운영자 자격 증명은 프로필 ID만 적으면 어느 연결 고객이든 청구할 수 있기 때문에, 헤더의 ID가 그 요청의 고객과 맞는지 앱에서 확인해야 한다. 틀리면 다른 고객의 조직에 오류 없이 청구된다.

성공 응답에는 누가 냈는지가 적혀 있지 않다. 어떤 요청을 user_profile로 보냈는지는 앱이 직접 기록해 둔다. 사용량은 Console의 User profiles 페이지와 사용량·비용 분석 API에서 프로필별로 볼 수 있고, 고객이 낸 요청은 amount에 0, list_amount에 정가가 더해진다. 보고서는 약 한 시간 간격으로 갱신되므로 실시간 차단에는 쓰지 않는다.

메시지 배치는 지원하지 않는다. 배치 항목에 bill_to: "user_profile"을 넣으면 그 항목만 invalid_request_error로 실패하고 아무에게도 청구되지 않는다. 일반 메시지 요청에서도 user_profile은 비용이 따로 드는 코드 실행 기능과 함께 쓸 수 없다(400).

고객이 정하는 월 지출 한도와 연결 해제

고객은 앱 하나당 월 지출 한도(spend cap)를 미국 달러로 정한다. 연결 승인 화면에서 처음 넣고, 연결 뒤에는 Console의 Linked platforms 페이지에서 Admin·Billing 역할이 바꾼다. 조직 전체의 Monthly spend limit과는 별개이고, 둘 중 하나라도 다 쓰면 고객에게 청구하는 요청은 거절된다. 한도는 정가 기준으로 세므로 협상 할인이 있는 조직은 실제 청구액과 한도에 잡히는 금액이 다를 수 있다.

한도에 닿으면 다음 달 1일 0시(UTC, 한국 시각 오전 9시)나 고객이 한도를 올리거나 없앨 때까지 요청이 거절되고, 변경이 반영되는 데는 약 1분이 걸린다. 앱은 고객의 한도도 사용 금액도 읽을 수 없다. 한도를 0달러로 두면 모든 요청이 거절된다. 계산 예를 하나 들면, 한도가 30달러인 고객이 월 중순까지 정가 기준 30달러어치를 쓰면 그 뒤 고객 청구 요청은 402를 받고, 앱은 bill_to: "self"로 다시 보내 운영자 비용으로 이어 가거나 고객에게 한도를 올려 달라고 안내해야 한다.

앱이 공개되기 전 시험 단계에는 더 좁은 제한이 걸린다.

클로드 API 결제 Linked billing 앱 시험 단계와 공개 후 지출 한도 차이 표
그림 2. 시험 중과 공개 후의 지출 한도 규칙. 출처: Anthropic 공식 문서 캡처(2026년 11월 18일)
항목시험·검토 중공개 후
승인 화면의 월 한도필수, 50달러 이하선택
금액 칸 초기값50달러비어 있음
한도 없이 계속없음있음
Console에서 한도 제거불가가능
고객이 정할 수 있는 최대 한도50달러사실상 제한 없음

고객이 앱을 끊으면 앱에는 웹훅이나 이메일 알림이 오지 않는다. 그 뒤 고객 청구 요청은 403 user_profile_not_billable이 되고, 프로필은 Console에 Unlinked로 표시된다. 같은 프로필로 승인 절차를 다시 돌리면 다시 연결된다. 고객 조직의 Admin·Billing 구성원에게는 연결·해제 이메일이 가지만 문서는 발송이나 도착을 보장하지 않는다고 밝힌다.

자주 만나는 오류와 점검 순서

아래 오류는 공식 문서의 오류 목록에서 가져왔다.

오류뜻할 일
403 user_profile_not_billable이 요청으로 고객에게 청구할 수 없다(이유는 응답에 없음)자격 증명과 프로필 ID, 연결 상태, 고객 조직 자격 순으로 확인. 급하면 bill_to: "self"로 재전송
402 linked_organization_spend_limit_reached앱 한도나 조직 월 한도를 다 썼거나 쓸 수 있는 크레딧이 없다고객에게 Linked platforms, Spend limits, Billing 페이지를 확인하게 안내
402 linked_organization_billing_unavailable조직이 정지됐거나 답변 도중 크레딧이 바닥났다재시도하지 않고 고객에게 계정 확인을 안내
503 overloaded_error지금은 청구 가능 여부를 확인하지 못했다retry-after만큼 기다린 뒤 재시도
400 user_profile_requireduser_profile인데 프로필 ID 헤더가 없다헤더 추가

토큰 교환 직후 10초를 지난 뒤에도 user_profile_not_billable이 계속되고 Console에는 Linked로 보이면, 거절된 요청의 request-id 응답 헤더와 전체 error.message를 기록해 Anthropic 계정 담당자에게 보낸다. 성공 기준은 고객이 승인을 마친 뒤 첫 요청이 200으로 돌아오고, Console의 User profiles 사용량에 그 프로필의 list_amount가 쌓이는 것이다.

이 기능은 사용자 프로필과 연결된 구조라서 같은 베타 계열의 클로드 API 메시지 스레드 베타처럼 헤더 하나로 켜는 기능과 달리 앱 등록과 고객 승인 화면 설계가 먼저 필요하다. 클로드 API 비용 구조를 먼저 보고 싶다면 Claude API 거부 응답 과금 기준 글이 같은 청구 질문을 다룬다.

자주 묻는 질문

클로드 프로·맥스 구독만 있어도 앱 사용료를 낼 수 있나요?

아니다. 구독 요금제만 쓰는 조직은 대상이 아니며, Console에서 산 크레딧이나 청구서 결제 같은 API 결제 수단이 있는 조직만 연결된다.

고객이 한도를 0달러로 두면 어떻게 되나요?

고객에게 청구하는 모든 요청이 402로 거절된다. 앱은 같은 요청을 bill_to: "self"로 다시 보내 운영자 비용으로 처리하거나 고객에게 한도 조정을 안내해야 한다.

고객이 연결을 끊으면 앱이 알림을 받나요?

받지 못한다. 문서에 따르면 웹훅도 이메일도 오지 않으므로, 403 user_profile_not_billable이 나올 때 연결 상태를 의심하고 Console의 User profiles에서 Unlinked 여부를 본다.

이 글이 도움이 되었다면 공유해주세요

최신 인사이트

관련 프로젝트

새 글을 이메일로 받아보세요

마케팅, 분석, 개발 인사이트를 정리해서 보내드려요.