Communitygithub.com

deangilmoreremix/videoremix.vip2

Clerk 청구 관리를 위한 스킬 - PricingTable 및 앱 내 체크아웃 드로어를 렌더링하고, 구독 플랜, B2B를 위한 시트 제한 플랜, has()를 통한 기능 권한, 청구 웹훅을 구성합니다. SaaS 수익화, 플랜 게이팅, 체크아웃 흐름, 체험판, 인보이스, 구독 라이프사이클 관리에 사용하세요.

videoremix.vip2란 무엇인가요?

이 스킬은 Clerk의 청구 시스템을 구성하고 SaaS 제품에서 구독 관리, 기능 게이팅 및 결제 처리를 가능하게 합니다. 주요 기능으로는 Clerk 대시보드나 `clerk enable billing` CLI 명령어를 통해 청구를 활성화하고, 사용자 및 조직별 플랜을 생성하며, `<PricingTable />` 컴포넌트로 가격 페이지를 렌더링하고, `has({ plan })` 또는 `has({ feature })`로 접근을 제어하는 것이 있습니다. 액션 테이블에는 PricingTable 렌더링, 서버/클라이언트 측 기능 권한 확인, 플랜 기반 API 라우트 보호, 그리고 구독 라이프사이클 이벤트를 처리하는 청구 웹훅이 포함됩니다. B2C 및 B2B 패턴 모두를 지원하며, 조직 구독 및 시트 제한 플랜에 대한 세부 가이드가 제공됩니다. 청구 API는 아직 실험 단계이므로 패키지 버전을 고정하는 것이 좋습니다. Stripe 계정은 프로덕션 결제 처리에만 필요하며, 개발 인스턴스는 공유 Clerk 개발 게이트웨이를 사용할 수 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/deangilmoreremix/videoremix.vip2/tree/HEAD/.agents/skills/clerk-billing

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

청구

중지, 필수 조건. 청구는 <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 스킬을 참조하십시오.

빠른 시작

  1. 청구 활성화, 대시보드 → 청구 → 설정 또는 clerk enable billing (Agent 우선 섹션 참조)을 통해 수행합니다. 건너뛰면 개발 환경에서는 cannot_render_billing_disabled 오류가 발생하고 프로덕션에서는 빈 화면이 렌더링됩니다.

  2. 해당 탭에서 플랜 생성, 대시보드 → 청구 → 플랜. 두 개의 탭이 있으며, 슬러그는 탭별로 범위가 지정되며 생성 후 이동할 수 없습니다:

    • 사용자 플랜 → <PricingTable /> (기본값 for="user")
    • 조직 플랜 → <PricingTable for="organization" />

    잘못된 탭은 빈 <PricingTable />의 가장 흔한 원인입니다. 플랜은 Clerk에 저장되며 Stripe와 동기화되지 않습니다.

  3. 플랜 내에 기능 추가, 대시보드 → 청구 → 플랜에서 플랜을 열고 기능 섹션을 사용합니다. 기능은 플랜별로 범위가 지정되며 전역이 아닙니다. 동일한 슬러그를 여러 플랜에 연결할 수 있습니다. has({ feature: 'export' })는 활성 플랜에 해당 슬러그가 포함된 경우 일치합니다.

  4. <PricingTable /> 렌더링 (B2B의 경우 for="organization" 전달).

  5. auth()의 has({ plan }) 또는 has({ feature })로 접근 게이팅.

  6. 구독 라이프사이클을 위한 청구 웹훅 처리.

대시보드 바로가기

액션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.mdB2C 구독 청구 패턴
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

… (번역을 위해 잘림)

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

deangilmoreremix/videoremix.vip2

Implement Clerk authentication for native Android apps using Kotlin and Jetpack Compose with clerk-android source-guided patterns. Use for prebuilt AuthView/UserButton or custom API-driven auth flows. Do not use for Expo or React Native projects.

deangilmoreremix/videoremix.vip2

Astro patterns with Clerk — middleware, SSR pages, island components, API routes, static vs SSR rendering. Triggers on: astro clerk, clerk astro middleware, astro protected page, clerk island component, astro API route auth, clerk astro SSR.

deangilmoreremix/videoremix.vip2

Clerk Backend REST API explorer and executor. Browse tags, inspect endpoint schemas, and execute authenticated requests. Use when listing users, managing organizations, or calling any Clerk API endpoint.

deangilmoreremix/videoremix.vip2

Chrome Extension auth with @clerk/chrome-extension -- popup/sidepanel setup, syncHost for OAuth/SAML via web app, createClerkClient for service workers and headless extensions, stable CRX ID. Triggers on: Chrome extension auth, Plasmo clerk, popup sign-in, syncHost, background service worker token, createClerkClient, headless extension.

deangilmoreremix/videoremix.vip2

>- Operate the Clerk CLI (`clerk` binary) for authentication, user/org/session management, deploy verification, instance config, env keys, and any Clerk Backend or Platform API call. Use when the user mentions Clerk management tasks, "list clerk users", "create a clerk user", "update organization", "pull clerk config", "clerk env pull", "clerk doctor", "clerk deploy", "clerk deploy status", "clerk api", or any ad-hoc Clerk API request. Prefer the CLI over raw HTTP: it handles auth, key resolution, app/instance targeting, and formatting automatically.

deangilmoreremix/videoremix.vip2

Custom authentication flows and component appearance - hooks (useSignIn, useSignUp), themes, colors, fonts, CSS. Use for custom sign-in/sign-up flows, appearance styling, visual customization, branding.

deangilmoreremix/videoremix.vip2

Agent skill / project related to launch or product demo video: deangilmoreremix/videoremix.vip2

관련 스킬