Facturación
DETENTE, requisito previo. La facturación debe estar habilitada antes de que cualquier uso de
<PricingTable />,<CheckoutButton />,has({ plan })ohas({ feature })funcione. Dos caminos: (1) Dashboard → Facturación → Configuración, o (2)clerk enable billing(ver "Configuración programática de facturación" más abajo). Habilitar crea automáticamente los planes predeterminadosfree_user/free_org. Las instancias de desarrollo pueden usar la puerta de enlace compartida de desarrollo de Clerk (no se necesita cuenta de Stripe); la producción requiere una cuenta de Stripe solo para el procesamiento de pagos.Nota: Las API de facturación aún son experimentales. Fija las versiones de tus paquetes
@clerk/nextjsyclerk-js. Consulta la habilidadclerkpara la tabla de versiones compatibles.
Inicio rápido
-
Habilita la facturación, a través de Dashboard → Facturación → Configuración o
clerk enable billing(ver sección "Configuración programática"). Omitir esto lanzacannot_render_billing_disableden desarrollo y renderiza vacío en producción. -
Crea planes en la pestaña correspondiente, Dashboard → Facturación → Planes. Dos pestañas, slugs con ámbito por pestaña, no se pueden mover después de la creación:
- Planes de Usuario →
<PricingTable />(por defectofor="user") - Planes de Organización →
<PricingTable for="organization" />
Elegir la pestaña incorrecta es la causa #1 de un
<PricingTable />vacío. Los planes residen en Clerk; no se sincronizan con Stripe. - Planes de Usuario →
-
Agrega funcionalidades dentro de un plan, abre el plan en Dashboard → Facturación → Planes, usa su sección de Funcionalidades. Las funcionalidades tienen ámbito por plan, no son globales. El mismo slug puede adjuntarse a múltiples planes;
has({ feature: 'export' })coincide si el plan activo contiene ese slug. -
Renderiza
<PricingTable />(pasafor="organization"para B2B). -
Restringe el acceso con
has({ plan })ohas({ feature })desdeauth(). -
Maneja webhooks de facturación para el ciclo de vida de suscripciones.
Accesos directos del Dashboard
| Acción | URL |
|---|---|
| Habilitar facturación | https://dashboard.clerk.com/last-active?path=billing/settings |
| Crear / editar planes | https://dashboard.clerk.com/last-active?path=billing/plans |
| Modo de membresía (coexistencia B2C + B2B) | https://dashboard.clerk.com/last-active?path=organizations-settings |
| Editar funcionalidades | Planes → haz clic en un plan → sección Funcionalidades (sin URL directa) |
Configuración programática de facturación (para agentes)
La configuración completa de facturación (alternancias de habilitación, planes, funcionalidades, adjuntos plan-funcionalidad) se puede editar a través de PLAPI sin tocar el Dashboard. Útil para que los agentes creen planes, repliquen configuraciones entre instancias o controlen por versiones la estructura de facturación.
Requisito previo: proyecto vinculado a la aplicación Clerk (clerk auth login + clerk link, ver clerk-setup).
Habilitar facturación mediante CLI
clerk enable billing # ambos objetivos (predeterminado, crea automáticamente planes free_user + free_org)
clerk enable billing --for org # solo organización
clerk enable billing --for user # solo usuario
Obtener la configuración actual de facturación
clerk config pull --keys billing > billing.json
Esto escribe la configuración actual de facturación (alternancias + planes + funcionalidades) para la instancia vinculada en billing.json.
Editar y aplicar
Edita billing.json para agregar o eliminar planes o funcionalidades, luego previsualiza el diff y aplica:
clerk config patch --file billing.json --dry-run
clerk config patch --file billing.json
Pasa --instance prod para apuntar a la instancia de producción en lugar de la de desarrollo.
PATCH directo (control total)
Para actualizaciones de planes/funcionalidades de una sola vez sin un archivo de configuración:
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
- Esto maneja la configuración de facturación (alternancias + catálogo de planes + funcionalidades). El ciclo de vida de suscripciones (usuarios eligiendo un plan, pago, renovación, cancelación) aún fluye a través de
<PricingTable />+ webhooks de facturación; consulta la habilidadclerk-webhookspara los eventos del ciclo de vida. - La manipulación del mapa de
featuresde nivel superior y los adjuntos plan-funcionalidad (sincronización) son totalmente compatibles a través del manejador de configuración de facturación de PLAPI.
¿Qué necesitas?
| Tarea | Referencia |
|---|---|
Props de <PricingTable />, <CheckoutButton />, patrones de facturación de <Show> | references/billing-components.md |
Patrones B2C (suscripciones de usuario individual, requisito previo de Membership optional) | references/b2c-patterns.md |
| Patrones B2B (suscripciones de organización, planes con límite de asientos, UI de facturación controlada por administrador) | references/b2b-patterns.md |
| Catálogo de eventos de webhook, formas de payload, plantillas de manejador | references/billing-webhooks.md |
Referencias
| Referencia | Descripción |
|---|---|
references/billing-components.md | <PricingTable /> y UI de suscripción |
references/b2c-patterns.md | Patrones de facturación de suscripciones B2C |
references/b2b-patterns.md | Facturación B2B con suscripciones de organización y planes con límite de asientos |
references/billing-webhooks.md | Manejo de eventos del ciclo de vida de suscripciones |
Documentación
Funcionalidades vs Planes: Cuándo usar cuál
Usa has({ feature: 'slug' }) cuando restrinjas una capacidad específica: exportación, analytics, acceso a API, registros de auditoría.
Usa has({ plan: 'slug' }) cuando restrinjas un nivel: mostrar el dashboard Pro, verificar el nivel de suscripción de la organización, redirigir a usuarios gratuitos.
| Escenario | Verificación correcta |
|---|---|
| Restringir el botón "Exportar CSV" | has({ feature: 'export' }) |
| Restringir la sección "Analytics" | has({ feature: 'analytics' }) |
| Restringir todo /dashboard/pro | has({ plan: 'pro' }) |
| Verificar si la organización tiene suscripción de equipo | has({ plan: 'org:team' }) |
| Restringir configuración de SSO | has({ feature: 'sso' }) |
Cuando un usuario dice "restringir la funcionalidad de exportación" o "restringir analytics", usa siempre has({ feature }). Solo usa has({ plan }) cuando la restricción sea el nivel del plan en sí mismo, no una capacidad específica dentro de él.
Patrones clave
1. Renderizar la tabla de precios
Muestra los planes disponibles a los usuarios con un solo componente:
import { PricingTable } from '@clerk/nextjs'
export default function PricingPage() {
return (
<main>
<h1>Elige un plan</h1>
<PricingTable />
</main>
)
}
<PricingTable /> renderiza automáticamente todos los planes configurados en el Dashboard de Clerk. Seleccionar un plan abre el cajón de pago integrado de Clerk. No se necesitan props para uso básico. Para B2B, pasa for="organization" para renderizar planes de organización en lugar de planes de usuario.
2. Verificar derechos de funcionalidad (lado del servidor)
Restringe por funcionalidades individuales; este es el enfoque preferido 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>
)
}
Las funcionalidades se configuran en Dashboard de Clerk → Facturación → Funcionalidades y se asignan a los planes. Usa has({ feature }) en lugar de has({ plan }) cuando restrinjas capacidades granulares; verifica la funcionalidad, no el plan.
3. Verificar derechos de funcionalidad (lado del cliente)
Usa useAuth() para la restricción de funcionalidades del lado del cliente. Combínalo con verificaciones del lado del servidor para una cobertura completa:
'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>
)
}
Los Componentes del Servidor usan auth(), los Componentes del Cliente usan useAuth(). Ambos soportan has({ feature }) y has({ plan }).
4. Verificar plan de suscripción del lado del servidor
Restringe el acceso por plan de suscripción (usa esto para restricciones de nivel, no para funcionalidades individuales):
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. Verificaciones de plan del lado del cliente
Usa el hook useAuth() para componentes del cliente:
'use client'
import { useAuth } from '@clerk/nextjs'
export function UpgradePrompt() {
const { has } = useAuth()
if (has?.({ plan: 'pro' })) {
return null
}
return (
<div>
<p>Actualiza a Pro para acceder a esta funcionalidad</p>
<a href="/pricing">Ver planes</a>
</div>
)
}
6. Facturación B2B basada en asientos con organizaciones
Los planes de organización pueden tener un límite de asientos (tope de membresía) que Clerk aplica al invitar. Usa el prefijo de slug org: en las verificaciones de plan del lado de la organización (ej. has({ plan: 'org:team' })) para mantener la restricción sin ambigüedades. Renderiza la página de precios B2B con <PricingTable for="organization" />, y usa <OrganizationProfile /> para la UI de facturación de la cuenta de la organización.
Consulta references/b2b-patterns.md para nombres de planes por niveles, invariantes de límite de asientos, facturación solo para administradores y manejadores de webhook.
7. Mostrar estado de la suscripción
Verifica planes específicos con has({ plan }), o usa useSubscription() para obtener detalles completos de la suscripción en componentes del cliente. No leas información del plan directamente de sessionClaims, esa no es la ruta compatible.
Componente del servidor, verifica planes 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>Plan actual</h2>
<p>Estás en el plan {currentPlan}</p>
{currentPlan === 'free' && <a href="/pricing">Actualizar</a>}
</div>
)
}
Componente del cliente, detalles completos de suscripción mediante 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">Elige un plan</a>
return (
<div>
<p>Estado: {subscription.status}</p>
{subscription.nextPayment && (
<p>Próximo pago: {subscription.nextPayment.date.toLocaleDateString()}</p>
)}
</div>
)
}
useSubscription()es solo para mostrar. Para verificaciones de autorización (restringir contenido o rutas), usa siemprehas({ plan })ohas({ feature }).
8. Proteger rutas de API por plan
Protege rutas 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: 'Se requiere plan Pro' }, { status: 403 })
}
return NextResponse.json({ data: 'datos premium' })
}
9. Manejar webhooks de facturación
Los nombres de eventos de Clerk difieren de los nombres de eventos de Stripe. Los webhooks de facturación de Clerk usan notación de puntos y camelCase, no el formato de guiones bajos de Stripe.
No existe el evento
subscription.canceled. La cancelación se dispara a nivel de elemento comosubscriptionItem.canceled.
Intención Nombre del evento en Stripe Nombre del evento en Clerk Suscripción creada customer.subscription.createdsubscription.createdSuscripción actualizada customer.subscription.updatedsubscription.updatedSuscripción activa (ninguno) subscription.activeSuscripción vencida (ninguno) subscription.pastDueElemento de suscripción cancelado customer.subscription.deletedsubscriptionItem.canceledElemento de suscripción vencido invoice.payment_failedsubscriptionItem.pastDueElemento de suscripción actualizado (ninguno) subscriptionItem.updatedElemento de suscripción activo (ninguno) subscriptionItem.activePróxima renovación de elemento de suscripción (ninguno) subscriptionItem.upcomingElemento de suscripción finalizado (ninguno) subscriptionItem.endedElemento de suscripción abandonado (ninguno) subscriptionItem.abandonedElemento de suscripción expirado (ninguno) subscriptionItem.expiredElemento de suscripción incompleto (ninguno) subscriptionItem.incompletePrueba gratuita próxima a finalizar (ninguno) subscriptionItem.freeTrialEndingIntento de pago creado (ninguno) paymentAttempt.createdIntento de pago actualizado (ninguno) paymentAttempt.updatedUsa siempre los nombres de eventos de Clerk, nunca los de Stripe, en las verificaciones
evt.type.
Forma del payload. Los payloads de webhook de facturación de Clerk están anidados. La entidad suscriptora se encuentra bajo
evt.data.payer(campos:user_id?,organization_id?). La información del plan está en cada elemento bajoevt.data.items[i].plan.slug. El id de suscripción es simplementeevt.data.id. Los elementos de suscripción no tienen un campo de referenciasubscription_id, por lo que en los manejadores desubscriptionItem.*identificas el registro por el id del elemento (evt.data.id) o buscas por pagador más plan.
Manejador mínimo para anclar el patrón (importa de @clerk/nextjs/webhooks, verifica, bifurca por nombre de evento de 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('Verificación fallida', { status: 400 })
}
if (evt.type === 'subscription.created') {
const { id, payer, items, status } = evt.data
const entityId = p
// ... [truncado para traducción]
Consulta references/billing-webhooks.md para el catálogo completo de eventos, formas de payload y plantillas de manejador con persistencia en DB y lógica empresarial típica.
Uso con Next.js App Router (Componentes del Servidor)
En el App Router, los Componentes del Servidor proporcionan has() directamente desde auth() sin serialización ni props adicionales. Restringe páginas enteras con has({ plan }) para verificaciones de nivel y has({ feature }) para funcionalidades específicas. Los componentes anidados heredan el contexto de autenticación a través del límite del componente del servidor sin necesidad de pasar props.
Notas importantes
- Habilitación requerida: La facturación debe estar habilitada antes de que cualquier componente de facturación o verificación funcione. Omite esta habilitación y obtendrás errores en desarrollo o tablas vacías en producción.
- Ámbito por pestaña: Los slugs de planes tienen ámbito según la pestaña de usuario u organización. No se pueden mover después de la creación. Usar la pestaña incorrecta es un error común.
- Experimental: Las API de facturación aún son experimentales. Fija las versiones de
@clerk/nextjsyclerk-js. - Facturación vs. ciclo de vida: La configuración de facturación (planes, funcionalidades) se maneja mediante el dashboard o CLI. El ciclo de vida de suscripciones (pago, renovación, cancelación) se maneja mediante componentes y webhooks.
- Preferir funcionalidades sobre planes: Al restringir capacidades específicas, usa
has({ feature }). Usahas({ plan })solo para restricciones de nivel del plan.