청구
중지, 필수 조건. 청구는
<PricingTable />,<CheckoutButton />,has({ plan })또는has({ feature })를 사용하기 전에 반드시 활성화되어야 합니다. 두 가지 방법: (1) 대시보드 → 청구 → 설정 또는 (2)clerk enable billing(아래 "Agent 우선: 프로그래매틱 청구 구성" 참조). 활성화하면 기본적으로free_user/free_org플랜이 자동 생성됩니다. 개발 인스턴스는 공유 Clerk 개발 게이트웨이를 사용할 수 있습니다(Stripe 계정 불필요). 프로덕션에서는 결제 처리만을 위해 Stripe 계정이 필요합니다.참고: 청구 API는 아직 실험 단계입니다.
@clerk/nextjs및clerk-js패키지 버전을 고정하세요. 지원되는 버전 테이블은clerk스킬을 참조하십시오.
빠른 시작
-
청구 활성화, 대시보드 → 청구 → 설정 또는
clerk enable billing(Agent 우선 섹션 참조)을 통해 수행합니다. 건너뛰면 개발 환경에서는cannot_render_billing_disabled오류가 발생하고 프로덕션에서는 빈 화면이 렌더링됩니다. -
해당 탭에서 플랜 생성, 대시보드 → 청구 → 플랜. 두 개의 탭이 있으며, 슬러그는 탭별로 범위가 지정되며 생성 후 이동할 수 없습니다:
- 사용자 플랜 →
<PricingTable />(기본값for="user") - 조직 플랜 →
<PricingTable for="organization" />
잘못된 탭은 빈
<PricingTable />의 가장 흔한 원인입니다. 플랜은 Clerk에 저장되며 Stripe와 동기화되지 않습니다. - 사용자 플랜 →
-
플랜 내에 기능 추가, 대시보드 → 청구 → 플랜에서 플랜을 열고 기능 섹션을 사용합니다. 기능은 플랜별로 범위가 지정되며 전역이 아닙니다. 동일한 슬러그를 여러 플랜에 연결할 수 있습니다.
has({ feature: 'export' })는 활성 플랜에 해당 슬러그가 포함된 경우 일치합니다. -
<PricingTable />렌더링 (B2B의 경우for="organization"전달). -
auth()의has({ plan })또는has({ feature })로 접근 게이팅. -
구독 라이프사이클을 위한 청구 웹훅 처리.
대시보드 바로가기
| 액션 | URL |
|---|---|
| 청구 활성화 | https://dashboard.clerk.com/last-active?path=billing/settings |
| 플랜 생성/편집 | https://dashboard.clerk.com/last-active?path=billing/plans |
| 멤버십 모드 (B2C + B2B 공존) | https://dashboard.clerk.com/last-active?path=organizations-settings |
| 기능 편집 | 플랜 → 플랜 클릭 → 기능 섹션 (직접 URL 없음) |
Agent 우선: 프로그래매틱 청구 구성
전체 청구 구성(활성화 토글, 플랜, 기능, 플랜-기능 연결)은 대시보드를 건드리지 않고 PLAPI를 통해 편집 가능합니다. 에이전트가 플랜을 시딩하거나, 인스턴스 간 구성을 복제하거나, 청구 구조를 버전 관리하는 데 유용합니다.
전제 조건: 프로젝트가 Clerk 앱에 연결되어 있어야 함 (clerk auth login + clerk link, clerk-setup 참조).
CLI를 통한 청구 활성화
clerk enable billing # 둘 다 (기본값, free_user + free_org 플랜 자동 생성)
clerk enable billing --for org # 조직만
clerk enable billing --for user # 사용자만
현재 청구 구성 가져오기
clerk config pull --keys billing > billing.json
연결된 인스턴스의 현재 청구 구성을(토글 + 플랜 + 기능) billing.json에 씁니다.
편집 및 적용
billing.json을 편집하여 플랜이나 기능을 추가/제거한 후, 차이점을 미리 보고 적용합니다:
clerk config patch --file billing.json --dry-run
clerk config patch --file billing.json
--instance prod를 전달하여 개발 대신 프로덕션 인스턴스를 대상으로 합니다.
원시 PATCH (전체 제어)
구성 파일 없이 일회성 플랜/기능 업데이트:
clerk api --platform PATCH /v1/platform/applications/<app_id>/instances/<ins_id>/config \
-d '{"billing":{"plans":[{"slug":"pro","name":"Pro","amount":2000,"currency":"usd","payer_type":"user","is_recurring":true}],"features":[{"slug":"export","name":"Export"}]}}'
참고 사항
- 이것은 청구 구성(토글 + 플랜 + 기능 카탈로그)을 처리합니다. 구독 라이프사이클(사용자가 플랜 선택, 체크아웃, 갱신, 취소)은 여전히
<PricingTable />+ 청구 웹훅을 통해 이루어집니다. 라이프사이클 이벤트는clerk-webhooks스킬을 참조하세요. - 최상위
features맵 조작 및 플랜-기능 연결(동기화)은 PLAPI 청구 구성 핸들러를 통해 완전히 지원됩니다.
무엇이 필요하신가요?
| 작업 | 참조 |
|---|---|
<PricingTable /> props, <CheckoutButton />, <Show> 청구 패턴 | references/billing-components.md |
B2C 패턴 (개인 사용자 구독, Membership optional 필수 조건) | references/b2c-patterns.md |
| B2B 패턴 (조직 구독, 시트 제한 플랜, 관리자 게이팅 청구 UI) | references/b2b-patterns.md |
| 웹훅 이벤트 카탈로그, 페이로드 구조, 핸들러 템플릿 | references/billing-webhooks.md |
참조
| 참조 | 설명 |
|---|---|
references/billing-components.md | <PricingTable /> 및 구독 UI |
references/b2c-patterns.md | B2C 구독 청구 패턴 |
references/b2b-patterns.md | 조직 구독 및 시트 제한 플랜을 사용한 B2B 청구 |
references/billing-webhooks.md | 구독 라이프사이클 이벤트 처리 |
문서
기능 vs 플랜: 언제 무엇을 사용할까
특정 기능을 게이팅할 때 has({ feature: 'slug' })를 사용하세요: 내보내기, 분석, API 액세스, 감사 로그 등.
티어를 게이팅할 때 has({ plan: 'slug' })를 사용하세요: 프로 대시보드 표시, 조직 구독 수준 확인, 무료 사용자 리디렉션 등.
| 시나리오 | 올바른 확인 |
|---|---|
| "Export CSV" 버튼 게이팅 | has({ feature: 'export' }) |
| "Analytics" 섹션 게이팅 | has({ feature: 'analytics' }) |
| /dashboard/pro 전체 게이팅 | has({ plan: 'pro' }) |
| 조직에 팀 구독이 있는지 확인 | has({ plan: 'org:team' }) |
| SSO 구성 게이팅 | has({ feature: 'sso' }) |
사용자가 "내보내기 기능 게이팅" 또는 "분석 게이팅"이라고 말하면 항상 has({ feature })를 사용하세요. 게이트가 특정 기능이 아닌 플랜 티어 자체인 경우에만 has({ plan })을 사용하세요.
주요 패턴
1. 가격 테이블 렌더링
단일 컴포넌트로 사용자에게 제공 가능한 플랜을 표시합니다:
import { PricingTable } from '@clerk/nextjs'
export default function PricingPage() {
return (
<main>
<h1>플랜 선택</h1>
<PricingTable />
</main>
)
}
<PricingTable />은 Clerk 대시보드에 구성된 모든 플랜을 자동으로 렌더링합니다. 플랜을 선택하면 Clerk의 앱 내 체크아웃 드로어가 열립니다. 기본 사용에는 props가 필요 없습니다. B2B의 경우 for="organization"을 전달하여 사용자 플랜 대신 조직 수준 플랜을 렌더링합니다.
2. 기능 권한 확인 (서버 측)
개별 기능으로 게이팅합니다. 특정 기능에 권장되는 방법입니다:
import { auth } from '@clerk/nextjs/server'
export default async function AnalyticsPage() {
const { has } = await auth()
const canViewAnalytics = has({ feature: 'analytics' })
const canExport = has({ feature: 'export' })
return (
<div>
{canViewAnalytics && <AnalyticsChart />}
{canExport && <ExportButton />}
</div>
)
}
기능은 Clerk 대시보드 → 청구 → 기능에서 구성되고 플랜에 할당됩니다. 세분화된 기능을 게이팅할 때는 has({ plan }) 대신 has({ feature })를 사용하세요. 플랜이 아닌 기능을 확인하세요.
3. 기능 권한 확인 (클라이언트 측)
클라이언트 측 기능 게이팅에는 useAuth()를 사용하세요. 전체 적용 범위를 위해 서버 측 확인과 결합하세요:
'use client'
import { useAuth } from '@clerk/nextjs'
export function FeatureGatedUI() {
const { has, isLoaded } = useAuth()
if (!isLoaded) return null
const canExport = has?.({ feature: 'export' })
const canAnalytics = has?.({ feature: 'analytics' })
return (
<div>
{canAnalytics && <AnalyticsSection />}
{canExport ? <ExportButton /> : <UpgradeToExport />}
</div>
)
}
서버 컴포넌트는 auth(), 클라이언트 컴포넌트는 useAuth()를 사용합니다. 둘 다 has({ feature })와 has({ plan })을 지원합니다.
4. 구독 플랜 확인 (서버 측)
구독 플랜으로 접근 게이팅 (개별 기능이 아닌 티어 수준 게이트에 사용):
import { auth } from '@clerk/nextjs/server'
import { redirect } from 'next/navigation'
export default async function ProDashboard() {
const { has } = await auth()
if (!has({ plan: 'pro' })) {
redirect('/pricing')
}
return <ProFeatures />
}
5. 클라이언트 측 플랜 확인
클라이언트 컴포넌트에는 useAuth() 훅 사용:
'use client'
import { useAuth } from '@clerk/nextjs'
export function UpgradePrompt() {
const { has } = useAuth()
if (has?.({ plan: 'pro' })) {
return null
}
return (
<div>
<p>이 기능에 접근하려면 Pro로 업그레이드하세요</p>
<a href="/pricing">플랜 보기</a>
</div>
)
}
6. 조직을 사용한 B2B 시트 기반 청구
조직 플랜은 Clerk가 초대 시 적용하는 시트 제한(멤버십 상한)을 가질 수 있습니다. 조직 측 플랜 확인에 org: 슬러그 접두사를 사용하여 게이팅이 명확하도록 하세요(예: has({ plan: 'org:team' })). B2B 가격 페이지를 <PricingTable for="organization" />으로 렌더링하고, 조직 계정 청구 UI에는 <OrganizationProfile />을 사용하세요.
계층형 플랜 이름 지정, 시트 제한 불변 조건, 관리자 전용 청구 및 웹훅 핸들러는 references/b2b-patterns.md를 참조하세요.
7. 구독 상태 표시
has({ plan })으로 특정 플랜을 확인하거나, 클라이언트 컴포넌트에서 전체 구독 세부 정보를 위해 useSubscription()을 사용하세요. sessionClaims에서 직접 플랜 정보를 읽지 마세요. 지원되는 경로가 아닙니다.
서버 컴포넌트, 특정 플랜 확인:
import { auth } from '@clerk/nextjs/server'
export default async function AccountPage() {
const { has } = await auth()
const currentPlan = has({ plan: 'pro' })
? 'pro'
: has({ plan: 'starter' })
? 'starter'
: 'free'
return (
<div>
<h2>현재 플랜</h2>
<p>현재 {currentPlan} 플랜을 사용 중입니다</p>
{currentPlan === 'free' && <a href="/pricing">업그레이드</a>}
</div>
)
}
클라이언트 컴포넌트, useSubscription()을 통한 전체 구독 세부 정보:
'use client'
import { useSubscription } from '@clerk/nextjs/experimental'
export function SubscriptionDetails() {
const { data: subscription, isLoading } = useSubscription()
if (isLoading) return null
if (!subscription) return <a href="/pricing">플랜 선택</a>
return (
<div>
<p>상태: {subscription.status}</p>
{subscription.nextPayment && (
<p>다음 결제: {subscription.nextPayment.date.toLocaleDateString()}</p>
)}
</div>
)
}
useSubscription()은 표시 전용입니다. 인증 확인(콘텐츠 또는 라우트 게이팅)에는 항상has({ plan })또는has({ feature })를 사용하세요.
8. 플랜별 API 라우트 보호
auth()를 사용하여 API 라우트 게이팅:
import { auth } from '@clerk/nextjs/server'
import { NextResponse } from 'next/server'
export async function GET() {
const { has } = await auth()
if (!has({ plan: 'pro' })) {
return NextResponse.json({ error: 'Pro 플랜 필요' }, { status: 403 })
}
return NextResponse.json({ data: '프리미엄 데이터' })
}
9. 청구 웹훅 처리
Clerk 이벤트 이름은 Stripe 이벤트 이름과 다릅니다. Clerk 청구 웹훅은 Stripe의 밑줄 형식이 아닌 점 표기법과 카멜케이스를 사용합니다.
subscription.canceled이벤트는 없습니다. 취소는 항목 수준에서subscriptionItem.canceled로 발생합니다.
의도 Stripe 이벤트 이름 Clerk 이벤트 이름 구독 생성됨 customer.subscription.createdsubscription.created구독 업데이트됨 customer.subscription.updatedsubscription.updated구독 활성 (없음) subscription.active구독 연체 (없음) subscription.pastDue구독 항목 취소됨 customer.subscription.deletedsubscriptionItem.canceled구독 항목 연체 invoice.payment_failedsubscriptionItem.pastDue구독 항목 업데이트됨 (없음) subscriptionItem.updated구독 항목 활성 (없음) subscriptionItem.active구독 항목 다가오는 갱신 (없음) subscriptionItem.upcoming구독 항목 종료됨 (없음) subscriptionItem.ended구독 항목 중단됨 (없음) subscriptionItem.abandoned구독 항목 만료됨 (없음) subscriptionItem.expired구독 항목 불완전 (없음) subscriptionItem.incomplete무료 체험판 곧 종료 (없음) subscriptionItem.freeTrialEnding결제 시도 생성됨 (없음) paymentAttempt.created결제 시도 업데이트됨 (없음) paymentAttempt.updated
evt.type확인 시 항상 Clerk의 이벤트 이름을 사용하고 Stripe의 이름은 사용하지 마세요.
페이로드 구조. Clerk 청구 웹훅 페이로드는 중첩되어 있습니다. 구독 엔터티는
evt.data.payer아래에 있습니다(필드:user_id?,organization_id?). 플랜 정보는evt.data.items[i].plan.slug아래 각 항목에 있습니다. 구독 ID는 단순히evt.data.id입니다. 구독 항목에는 역참조subscription_id필드가 없으므로,subscriptionItem.*핸들러에서는 항목 ID(evt.data.id)로 레코드를 식별하거나 지불자와 플랜으로 조회합니다.
패턴을 고정하는 최소 핸들러 (@clerk/nextjs/webhooks에서 가져오기, 확인, Clerk 이벤트 이름으로 분기):
import { verifyWebhook } from '@clerk/nextjs/webhooks'
import { NextRequest } from 'next/server'
import { db } from '@/lib/db'
export async function POST(req: NextRequest) {
let evt
try {
evt = await verifyWebhook(req)
} catch {
return new Response('확인 실패', { status: 400 })
}
if (evt.type === 'subscription.created') {
const { id, payer, items, status } = evt.data
const entityId = p
… (번역을 위해 잘림)