Faturamento
PARE, pré-requisito. O faturamento deve estar habilitado antes de qualquer uso de
<PricingTable />,<CheckoutButton />,has({ plan })ouhas({ feature }). Dois caminhos: (1) Painel → Faturamento → Configurações, ou (2)clerk enable billing(veja "Abordagem agente: Configuração programática de faturamento" abaixo). Habilitar cria automaticamente os planos padrãofree_user/free_org. Instâncias de desenvolvimento podem usar o gateway de desenvolvimento compartilhado do Clerk (sem necessidade de conta Stripe); produção requer uma conta Stripe apenas para processamento de pagamentos.Nota: As APIs de faturamento ainda são experimentais. Fixe as versões dos pacotes
@clerk/nextjseclerk-js. Consulte a skillclerkpara a tabela de versões suportadas.
Início Rápido
-
Habilite o Faturamento, via Painel → Faturamento → Configurações ou
clerk enable billing(veja a seção Abordagem agente). Pular esta etapa geracannot_render_billing_disabledem desenvolvimento e renderiza vazio em produção. -
Crie planos na aba correspondente, Painel → Faturamento → Planos. Duas abas, os slugs têm escopo por aba e não podem ser movidos após a criação:
- Planos de Usuário →
<PricingTable />(padrãofor="user") - Planos de Organização →
<PricingTable for="organization" />
Aba errada é a causa #1 de um
<PricingTable />vazio. Os planos residem no Clerk; não são sincronizados com o Stripe. - Planos de Usuário →
-
Adicione funcionalidades dentro de um plano, abra o plano no Painel → Faturamento → Planos, use sua seção de Funcionalidades. As funcionalidades têm escopo por plano, não são globais. O mesmo slug pode ser anexado a vários planos;
has({ feature: 'export' })corresponde se o plano ativo contiver esse slug. -
Renderize
<PricingTable />(passefor="organization"para B2B). -
Bloqueie o acesso com
has({ plan })ouhas({ feature })doauth(). -
Lide com webhooks de faturamento para o ciclo de vida das assinaturas.
Atalhos do Painel
| Ação | URL |
|---|---|
| Habilitar Faturamento | https://dashboard.clerk.com/last-active?path=billing/settings |
| Criar / editar planos | https://dashboard.clerk.com/last-active?path=billing/plans |
| Modo de associação (coexistência B2C + B2B) | https://dashboard.clerk.com/last-active?path=organizations-settings |
| Editar funcionalidades | Planos → clique em um plano → seção Funcionalidades (sem URL direta) |
Abordagem agente: Configuração programática de faturamento
A configuração completa de faturamento (alternâncias de ativação, planos, funcionalidades, anexos plano-funcionalidade) é editável via PLAPI sem tocar no Painel. Útil para agentes semearem planos, replicarem configuração entre instâncias ou versionarem a estrutura de faturamento.
Pré-requisito: projeto vinculado ao aplicativo Clerk (clerk auth login + clerk link, veja clerk-setup).
Habilitar Faturamento via CLI
clerk enable billing # ambos os alvos (padrão, cria automaticamente free_user + free_org)
clerk enable billing --for org # apenas organização
clerk enable billing --for user # apenas usuário
Puxar a configuração atual de faturamento
clerk config pull --keys billing > billing.json
Isso escreve a configuração atual de faturamento (alternâncias + planos + funcionalidades) para a instância vinculada em billing.json.
Editar e aplicar
Edite billing.json para adicionar/remover planos ou funcionalidades, então visualize o diff e aplique:
clerk config patch --file billing.json --dry-run
clerk config patch --file billing.json
Passe --instance prod para direcionar a instância de produção em vez de desenvolvimento.
PATCH direto (controle total)
Para atualizações únicas de plano/funcionalidade sem um arquivo de configuração:
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"}]}}'
Notas
- Isso lida com a configuração de faturamento (alternâncias + catálogo de planos + funcionalidades). O ciclo de vida da assinatura (usuários escolhendo um plano, checkout, renovação, cancelamento) ainda flui através de
<PricingTable />+ webhooks de faturamento, veja a skillclerk-webhookspara os eventos do ciclo de vida. - A manipulação do mapa
featuresde nível superior e anexos plano-funcionalidade (sincronização) são totalmente suportados através do manipulador de configuração de faturamento da PLAPI.
Do Que Você Precisa?
| Tarefa | Referência |
|---|---|
Propriedades do <PricingTable />, <CheckoutButton />, padrões de faturamento <Show> | references/billing-components.md |
Padrões B2C (assinaturas de usuário individuais, pré-requisito Membership optional) | references/b2c-patterns.md |
| Padrões B2B (assinaturas de organização, planos com limite de assentos, interface de faturamento gerenciada por administrador) | references/b2b-patterns.md |
| Catálogo de eventos de webhook, formatos de payload, modelos de manipulador | references/billing-webhooks.md |
Referências
| Referência | Descrição |
|---|---|
references/billing-components.md | <PricingTable /> e interface de assinatura |
references/b2c-patterns.md | Padrões de faturamento de assinatura B2C |
references/b2b-patterns.md | Faturamento B2B com assinaturas de organização e planos com limite de assentos |
references/billing-webhooks.md | Manipulação de eventos do ciclo de vida da assinatura |
Documentação
Funcionalidades vs Planos: Quando Usar Cada Um
Use has({ feature: 'slug' }) ao bloquear uma capacidade específica, exportação, análises, acesso à API, logs de auditoria.
Use has({ plan: 'slug' }) ao bloquear um nível, mostrando o painel pro, verificando o nível de assinatura da organização, redirecionando usuários gratuitos.
| Cenário | Verificação correta |
|---|---|
| Bloquear o botão "Exportar CSV" | has({ feature: 'export' }) |
| Bloquear a seção "Análises" | has({ feature: 'analytics' }) |
| Bloquear todo /dashboard/pro | has({ plan: 'pro' }) |
| Verificar se a organização tem assinatura de equipe | has({ plan: 'org:team' }) |
| Bloquear configuração de SSO | has({ feature: 'sso' }) |
Quando um usuário disser "bloqueie a funcionalidade de exportação" ou "bloqueie análises", sempre use has({ feature }). Use has({ plan }) apenas quando o bloqueio for o próprio nível do plano, não uma capacidade específica dentro dele.
Padrões Principais
1. Renderizar a Tabela de Preços
Mostre os planos disponíveis aos usuários com um único componente:
import { PricingTable } from '@clerk/nextjs'
export default function PricingPage() {
return (
<main>
<h1>Escolha um plano</h1>
<PricingTable />
</main>
)
}
<PricingTable /> renderiza automaticamente todos os planos configurados no Painel do Clerk. Selecionar um plano abre o drawer de checkout no aplicativo do Clerk. Nenhuma propriedade necessária para uso básico. Para B2B, passe for="organization" para renderizar planos de nível de organização em vez de planos de usuário.
2. Verificar Direitos de Funcionalidade (Lado do Servidor)
Bloqueie por funcionalidades individuais, esta é a abordagem preferida para capacidades específicas:
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>
)
}
As funcionalidades são configuradas no Painel do Clerk → Faturamento → Funcionalidades e atribuídas a planos. Use has({ feature }) em vez de has({ plan }) ao bloquear capacidades granulares, verifique a funcionalidade, não o plano.
3. Verificar Direitos de Funcionalidade (Lado do Cliente)
Use useAuth() para bloqueio de funcionalidades no lado do cliente. Combine com verificações no lado do servidor para cobertura total:
'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>
)
}
Componentes de Servidor usam auth(), Componentes de Cliente usam useAuth(). Ambos suportam has({ feature }) e has({ plan }).
4. Verificar Plano de Assinatura no Lado do Servidor
Bloqueie o acesso por plano de assinatura (use isso para bloqueios de nível, não para funcionalidades individuais):
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. Verificações de Plano no Lado do Cliente
Use o hook useAuth() para componentes cliente:
'use client'
import { useAuth } from '@clerk/nextjs'
export function UpgradePrompt() {
const { has } = useAuth()
if (has?.({ plan: 'pro' })) {
return null
}
return (
<div>
<p>Atualize para Pro para acessar esta funcionalidade</p>
<a href="/pricing">Ver planos</a>
</div>
)
}
6. Faturamento B2B Baseado em Assentos com Organizações
Planos de organização podem ter um limite de assentos (limite de membros) que o Clerk aplica no momento do convite. Use o prefixo org: nas verificações de plano do lado da organização (ex.: has({ plan: 'org:team' })) para manter o bloqueio inequívoco. Renderize a página de preços B2B com <PricingTable for="organization" /> e use <OrganizationProfile /> para a interface de faturamento da conta da organização.
Consulte references/b2b-patterns.md para nomenclatura de planos em camadas, invariantes de limite de assentos, faturamento apenas para administradores e manipuladores de webhook.
7. Exibir Status da Assinatura
Verifique planos específicos com has({ plan }), ou use useSubscription() para detalhes completos da assinatura em componentes cliente. Não leia informações do plano de sessionClaims diretamente, esse não é o caminho suportado.
Componente de servidor, verifique planos específicos:
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>Plano Atual</h2>
<p>Você está no plano {currentPlan}</p>
{currentPlan === 'free' && <a href="/pricing">Atualizar</a>}
</div>
)
}
Componente cliente, detalhes completos da assinatura via 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">Escolha um plano</a>
return (
<div>
<p>Status: {subscription.status}</p>
{subscription.nextPayment && (
<p>Próximo pagamento: {subscription.nextPayment.date.toLocaleDateString()}</p>
)}
</div>
)
}
useSubscription()é apenas para exibição. Para verificações de autorização (bloqueio de conteúdo ou rotas), sempre usehas({ plan })ouhas({ feature }).
8. Proteger Rotas de API por Plano
Bloqueie rotas de API usando auth():
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: 'Plano Pro necessário' }, { status: 403 })
}
return NextResponse.json({ data: 'dados premium' })
}
9. Lidar com Webhooks de Faturamento
Os nomes de eventos do Clerk diferem dos nomes de eventos do Stripe. Os webhooks de faturamento do Clerk usam notação por pontos e camelCase, não o formato underscore do Stripe.
Não há evento
subscription.canceled. O cancelamento é acionado no nível do item comosubscriptionItem.canceled.
Intenção Nome do evento Stripe Nome do evento Clerk Assinatura criada customer.subscription.createdsubscription.createdAssinatura atualizada customer.subscription.updatedsubscription.updatedAssinatura ativa (nenhum) subscription.activeAssinatura vencida (nenhum) subscription.pastDueItem de assinatura cancelado customer.subscription.deletedsubscriptionItem.canceledItem de assinatura vencido invoice.payment_failedsubscriptionItem.pastDueItem de assinatura atualizado (nenhum) subscriptionItem.updatedItem de assinatura ativo (nenhum) subscriptionItem.activePróxima renovação de item de assinatura (nenhum) subscriptionItem.upcomingItem de assinatura encerrado (nenhum) subscriptionItem.endedItem de assinatura abandonado (nenhum) subscriptionItem.abandonedItem de assinatura expirado (nenhum) subscriptionItem.expiredItem de assinatura incompleto (nenhum) subscriptionItem.incompleteTeste gratuito terminando em breve (nenhum) subscriptionItem.freeTrialEndingTentativa de pagamento criada (nenhum) paymentAttempt.createdTentativa de pagamento atualizada (nenhum) paymentAttempt.updatedSempre use os nomes de eventos do Clerk, nunca os do Stripe, nas verificações
evt.type.
Formato do payload. Os payloads dos webhooks de faturamento do Clerk são aninhados. A entidade assinante está em
evt.data.payer(campos:user_id?,organization_id?). As informações do plano estão em cada item sobevt.data.items[i].plan.slug. O id da assinatura é simplesmenteevt.data.id. Os itens de assinatura não carregam um camposubscription_idde referência inversa, portanto, nos manipuladoressubscriptionItem.*, você identifica o registro pelo id do item (evt.data.id) ou pesquisa pelo pagador mais o plano.
Manipulador mínimo para ancorar o padrão (importe de @clerk/nextjs/webhooks, verifique, ramifique pelo nome do evento 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('Verificação falhou', { status: 400 })
}
if (evt.type === 'subscription.created') {
const { id, payer, items, status } = evt.data
const entityId = p
… [truncado para tradução]