Communitygithub.com

deangilmoreremix/videoremix.vip2

Faturamento Clerk para gerenciamento de assinaturas - renderize a PricingTable do Clerk e o drawer de checkout no aplicativo, configure planos de assinatura, planos com limite de assentos para B2B, direitos de funcionalidades com has(), e webhooks de faturamento. Use para monetização SaaS, bloqueio por plano, fluxos de checkout, testes, faturamento e gerenciamento do ciclo de vida de assinaturas.

O que é videoremix.vip2?

Esta skill configura e gerencia o sistema de faturamento do Clerk para aplicações SaaS. Ela permite habilitar o faturamento, criar e gerenciar planos (de usuário e organização), definir funcionalidades por plano, renderizar a tabela de preços (`<PricingTable />`) e o botão de checkout (`<CheckoutButton />`), além de verificar direitos de acesso com `has({ plan })` ou `has({ feature })`. A skill suporta tanto o fluxo via Dashboard do Clerk quanto uma abordagem programática via CLI (`clerk enable billing`, `clerk config patch`) para automação por agentes de IA. Também abrange padrões B2C e B2B, incluindo planos com limite de assentos, e fornece uma tabela de eventos de webhook para gerenciar o ciclo de vida das assinaturas. É essencial para qualquer projeto Clerk que precise de monetização, bloqueio de recursos e gerenciamento de assinaturas.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Faturamento

PARE, pré-requisito. O faturamento deve estar habilitado antes de qualquer uso de <PricingTable />, <CheckoutButton />, has({ plan }) ou has({ 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ão free_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/nextjs e clerk-js. Consulte a skill clerk para a tabela de versões suportadas.

Início Rápido

  1. Habilite o Faturamento, via Painel → Faturamento → Configurações ou clerk enable billing (veja a seção Abordagem agente). Pular esta etapa gera cannot_render_billing_disabled em desenvolvimento e renderiza vazio em produção.

  2. 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ão for="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.

  3. 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.

  4. Renderize <PricingTable /> (passe for="organization" para B2B).

  5. Bloqueie o acesso com has({ plan }) ou has({ feature }) do auth().

  6. Lide com webhooks de faturamento para o ciclo de vida das assinaturas.

Atalhos do Painel

AçãoURL
Habilitar Faturamentohttps://dashboard.clerk.com/last-active?path=billing/settings
Criar / editar planoshttps://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 funcionalidadesPlanos → 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 skill clerk-webhooks para os eventos do ciclo de vida.
  • A manipulação do mapa features de 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?

TarefaReferê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 manipuladorreferences/billing-webhooks.md

Referências

ReferênciaDescrição
references/billing-components.md<PricingTable /> e interface de assinatura
references/b2c-patterns.mdPadrões de faturamento de assinatura B2C
references/b2b-patterns.mdFaturamento B2B com assinaturas de organização e planos com limite de assentos
references/billing-webhooks.mdManipulaçã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árioVerificação correta
Bloquear o botão "Exportar CSV"has({ feature: 'export' })
Bloquear a seção "Análises"has({ feature: 'analytics' })
Bloquear todo /dashboard/prohas({ plan: 'pro' })
Verificar se a organização tem assinatura de equipehas({ plan: 'org:team' })
Bloquear configuração de SSOhas({ 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 use has({ plan }) ou has({ 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 como subscriptionItem.canceled.

IntençãoNome do evento StripeNome do evento Clerk
Assinatura criadacustomer.subscription.createdsubscription.created
Assinatura atualizadacustomer.subscription.updatedsubscription.updated
Assinatura ativa(nenhum)subscription.active
Assinatura vencida(nenhum)subscription.pastDue
Item de assinatura canceladocustomer.subscription.deletedsubscriptionItem.canceled
Item de assinatura vencidoinvoice.payment_failedsubscriptionItem.pastDue
Item de assinatura atualizado(nenhum)subscriptionItem.updated
Item de assinatura ativo(nenhum)subscriptionItem.active
Próxima renovação de item de assinatura(nenhum)subscriptionItem.upcoming
Item de assinatura encerrado(nenhum)subscriptionItem.ended
Item de assinatura abandonado(nenhum)subscriptionItem.abandoned
Item de assinatura expirado(nenhum)subscriptionItem.expired
Item de assinatura incompleto(nenhum)subscriptionItem.incomplete
Teste gratuito terminando em breve(nenhum)subscriptionItem.freeTrialEnding
Tentativa de pagamento criada(nenhum)paymentAttempt.created
Tentativa de pagamento atualizada(nenhum)paymentAttempt.updated

Sempre 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 sob evt.data.items[i].plan.slug. O id da assinatura é simplesmente evt.data.id. Os itens de assinatura não carregam um campo subscription_id de referência inversa, portanto, nos manipuladores subscriptionItem.*, 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]

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

Habilidades Relacionadas