计费
注意,先决条件。 在使用任何
<PricingTable />、<CheckoutButton />、has({ plan })或has({ feature })之前,必须先启用计费。有两种方式:(1) Dashboard → Billing → Settings,或 (2)clerk enable billing(参见下文“Agent-first: 程序化计费配置”)。启用后会自动创建默认的free_user/free_org计划。开发实例可以使用共享的 Clerk 开发网关(无需 Stripe 账户);生产环境则需要 Stripe 账户来处理付款。注意:计费 API 仍处于实验阶段。请锁定你的
@clerk/nextjs和clerk-js包版本。支持的版本表请参见clerk技能。
快速开始
-
启用计费,通过 Dashboard → Billing → Settings 或
clerk enable billing(参见 Agent-first 部分)。跳过此步骤会在开发环境中抛出cannot_render_billing_disabled错误,在生产环境则渲染为空。 -
在对应的标签页中创建计划,Dashboard → Billing → Plans。两个标签页,slug 在每个标签页内作用域限定,创建后不可移动:
- 用户计划(User Plans) →
<PricingTable />(默认为for="user") - 组织计划(Organization Plans) →
<PricingTable for="organization" />
标签页错误是
<PricingTable />渲染为空的头号原因。计划存在于 Clerk 中;不会同步到 Stripe。 - 用户计划(User Plans) →
-
在计划内添加功能,在 Dashboard → Billing → Plans 中打开该计划,使用其功能(Features)部分。功能在每个计划内作用域限定,不是全局的。同一个 slug 可以附加到多个计划;如果用户的活跃计划包含该 slug,则
has({ feature: 'export' })将匹配。 -
渲染
<PricingTable />(对于 B2B,传入for="organization")。 -
使用
auth()中的has({ plan })或has({ feature })控制访问。 -
处理订阅生命周期的计费 Webhook。
Dashboard 快捷方式
| 操作 | 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 |
| 编辑功能 | 计划 → 点击一个计划 → 功能(Features)部分 (无直接 URL) |
Agent-first: 程序化计费配置
完整的计费配置(启用开关、计划、功能、计划-功能附件)都可以通过 PLAPI 编辑,而无需接触 Dashboard。这对于 Agent 播种计划、跨实例复制配置或对计费结构进行版本控制非常有用。
前置条件:项目已链接到 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 />+ 计费 Webhook 流转,生命周期事件请参见clerk-webhooks技能。 - 顶级
features映射操作和计划-功能附件(同步)完全通过 PLAPI 计费配置处理器支持。
你需要什么?
| 任务 | 参考 |
|---|---|
<PricingTable /> 属性、<CheckoutButton />、<Show> 计费模式 | references/billing-components.md |
B2C 模式 (个人用户订阅、Membership optional 前置条件) | references/b2c-patterns.md |
| B2B 模式 (组织订阅、席位限制计划、管理员控制的计费 UI) | references/b2b-patterns.md |
| Webhook 事件目录、负载结构、处理器模板 | 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' }),例如:显示专业版仪表盘、检查组织订阅级别、重定向免费用户。
| 场景 | 正确的检查方式 |
|---|---|
| 控制“导出 CSV”按钮 | has({ feature: 'export' }) |
| 控制“分析”部分 | 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 Dashboard 中配置的所有计划。选择计划会打开 Clerk 的应用内结账抽屉。基本用法无需属性。对于 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 Dashboard → Billing → Features 中配置,并分配给计划。在控制细粒度能力时,使用 has({ feature }) 而非 has({ plan }),检查功能,而非计划。
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>升级到专业版以使用此功能</p>
<a href="/pricing">查看计划</a>
</div>
)
}
6. B2B 基于席位的组织计费
组织计划可以带有一个席位限制(成员上限),Clerk 在邀请时会强制执行。在对组织方计划检查时使用 org: slug 前缀(例如 has({ plan: 'org:team' }))以保持控制明确无误。使用 <PricingTable for="organization" /> 渲染 B2B 定价页面,并使用 <OrganizationProfile /> 作为组织账户的计费 UI。
有关层级计划命名、席位限制不变性、仅管理员计费和 Webhook 处理器,请参见 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: '需要专业版计划' }, { status: 403 })
}
return NextResponse.json({ data: '高级数据' })
}
9. 处理计费 Webhook
Clerk 事件名称与 Stripe 事件名称不同。 Clerk 计费 Webhook 使用点号表示法和驼峰命名,而非 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 计费 Webhook 负载是嵌套的。订阅实体位于
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 = payer.user_id ?? payer.organization_id
// ... 处理新订阅 ...
}
if (evt.type === 'subscriptionItem.canceled') {
const { id, payer, items } = evt.data
const planSlug = items?.[0]?.plan?.slug
// ... 处理订阅取消 ...
}
return new Response('Webhook 已接收', { status: 200 })
}
10. 试用期
在 Clerk Dashboard → Billing → Plans 中编辑计划时,可以为任何计费计划添加试用期。
试用期在计划级别配置:
{
"slug": "pro",
"name": "Pro",
"amount": 2000,
"currency": "usd",
"trial_period_days": 14
}
试用期会在每个计费周期首次续订时自动应用。试用期结束时,会触发 subscriptionItem.freeTrialEnding webhook。
11. 发票
发票通过 Stripe 自动生成。Clerk 不直接创建或管理发票。如需自定义发票,请在 Stripe Dashboard 中配置。
计费 Webhook paymentAttempt.* 包含有关付款尝试的信息。