Communitygithub.com

deangilmoreremix/videoremix.vip2

Facturación de Clerk para gestión de suscripciones: renderiza PricingTable y cajón de pago en la aplicación, configura planes de suscripción, planes con límite de asientos para B2B, derechos de funcionalidad con has() y webhooks de facturación. Útil para monetización SaaS, restricción por plan, flujos de pago, pruebas, facturación y gestión del ciclo de vida de suscripciones.

¿Qué es videoremix.vip2?

Esta habilidad de Clerk proporciona una solución completa de facturación y gestión de suscripciones para aplicaciones SaaS. Permite habilitar la facturación, crear y gestionar planes (tanto de usuario como de organización), renderizar tablas de precios (PricingTable) y un cajón de pago integrado, verificar derechos de funcionalidad con `has({ feature })` y accesos basados en plan con `has({ plan })`, y manejar webhooks de facturación para eventos del ciclo de vida de suscripciones. Es compatible con Next.js (App Router) y otras plataformas a través de Clerk. La configuración se puede realizar tanto desde el panel de control de Clerk como de forma programática mediante la CLI de Clerk (comandos como `clerk enable billing`, `clerk config pull`, `clerk config patch`), lo que la hace ideal para agentes de IA que necesitan automatizar la configuración de facturación en múltiples entornos. Es importante habilitar la facturación antes de usar cualquier componente o verificación relacionada, y se debe tener cuidado de crear los planes en la pestaña correcta (usuario u organización) para evitar tablas de precios vacías.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Facturación

DETENTE, requisito previo. La facturación debe estar habilitada antes de que cualquier uso de <PricingTable />, <CheckoutButton />, has({ plan }) o has({ 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 predeterminados free_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/nextjs y clerk-js. Consulta la habilidad clerk para la tabla de versiones compatibles.

Inicio rápido

  1. 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 lanza cannot_render_billing_disabled en desarrollo y renderiza vacío en producción.

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

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

  4. Renderiza <PricingTable /> (pasa for="organization" para B2B).

  5. Restringe el acceso con has({ plan }) o has({ feature }) desde auth().

  6. Maneja webhooks de facturación para el ciclo de vida de suscripciones.

Accesos directos del Dashboard

AcciónURL
Habilitar facturaciónhttps://dashboard.clerk.com/last-active?path=billing/settings
Crear / editar planeshttps://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 funcionalidadesPlanes → 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 habilidad clerk-webhooks para los eventos del ciclo de vida.
  • La manipulación del mapa de features de 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?

TareaReferencia
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 manejadorreferences/billing-webhooks.md

Referencias

ReferenciaDescripción
references/billing-components.md<PricingTable /> y UI de suscripción
references/b2c-patterns.mdPatrones de facturación de suscripciones B2C
references/b2b-patterns.mdFacturación B2B con suscripciones de organización y planes con límite de asientos
references/billing-webhooks.mdManejo 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.

EscenarioVerificación correcta
Restringir el botón "Exportar CSV"has({ feature: 'export' })
Restringir la sección "Analytics"has({ feature: 'analytics' })
Restringir todo /dashboard/prohas({ plan: 'pro' })
Verificar si la organización tiene suscripción de equipohas({ plan: 'org:team' })
Restringir configuración de SSOhas({ 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 siempre has({ plan }) o has({ 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 como subscriptionItem.canceled.

IntenciónNombre del evento en StripeNombre del evento en Clerk
Suscripción creadacustomer.subscription.createdsubscription.created
Suscripción actualizadacustomer.subscription.updatedsubscription.updated
Suscripción activa(ninguno)subscription.active
Suscripción vencida(ninguno)subscription.pastDue
Elemento de suscripción canceladocustomer.subscription.deletedsubscriptionItem.canceled
Elemento de suscripción vencidoinvoice.payment_failedsubscriptionItem.pastDue
Elemento de suscripción actualizado(ninguno)subscriptionItem.updated
Elemento de suscripción activo(ninguno)subscriptionItem.active
Próxima renovación de elemento de suscripción(ninguno)subscriptionItem.upcoming
Elemento de suscripción finalizado(ninguno)subscriptionItem.ended
Elemento de suscripción abandonado(ninguno)subscriptionItem.abandoned
Elemento de suscripción expirado(ninguno)subscriptionItem.expired
Elemento de suscripción incompleto(ninguno)subscriptionItem.incomplete
Prueba gratuita próxima a finalizar(ninguno)subscriptionItem.freeTrialEnding
Intento de pago creado(ninguno)paymentAttempt.created
Intento de pago actualizado(ninguno)paymentAttempt.updated

Usa 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 bajo evt.data.items[i].plan.slug. El id de suscripción es simplemente evt.data.id. Los elementos de suscripción no tienen un campo de referencia subscription_id, por lo que en los manejadores de subscriptionItem.* 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/nextjs y clerk-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 }). Usa has({ plan }) solo para restricciones de nivel del plan.

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

Skills relacionados