Communitygithub.com

deangilmoreremix/videoremix.vip2

Facturation Clerk pour la gestion des abonnements - affichez le PricingTable de Clerk et le tiroir de paiement intégré, configurez les plans d'abonnement, les plans avec limite de sièges pour le B2B, les droits d'accès aux fonctionnalités avec has(), et les webhooks de facturation. Utilisez-le pour la monétisation SaaS, le gating des plans, les flux de paiement, les essais, la facturation et la gestion du cycle de vie des abonnements.

Qu'est-ce que videoremix.vip2 ?

Cette compétence implémente la gestion complète de la facturation et des abonnements basée sur Clerk pour les applications SaaS. Elle permet d'afficher le composant `<PricingTable />` pour présenter les plans aux utilisateurs, d'utiliser `<CheckoutButton />` pour lancer le flux de paiement intégré, et de gérer les droits d'accès avec `has({ plan })` et `has({ feature })` côté serveur et client. La compétence prend en charge à la fois les modèles B2C (abonnements individuels) et B2B (abonnements d'organisation avec plans à sièges), ainsi que la configuration programmatique via la CLI (`clerk enable billing`, `clerk config patch`) pour les agents. Elle inclut également la gestion des webhooks de facturation pour le cycle de vie des abonnements, avec des noms d'événements Clerk spécifiques (ex: `subscriptionItem.canceled`) différents de ceux de Stripe. L'activation de la facturation est un prérequis obligatoire avant toute utilisation des composants ou des vérifications de droits.

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Facturation

ARRÊTEZ-VOUS, prérequis. La facturation doit être activée avant toute utilisation de <PricingTable />, <CheckoutButton />, has({ plan }) ou has({ feature }). Deux chemins : (1) Tableau de bord → Facturation → Paramètres, ou (2) clerk enable billing (voir « Agent-first : Configuration de facturation programmatique » ci-dessous). L'activation crée automatiquement les plans par défaut free_user / free_org. Les instances de développement peuvent utiliser la passerelle de développement partagée Clerk (aucun compte Stripe nécessaire) ; la production nécessite un compte Stripe pour le traitement des paiements uniquement.

Remarque : Les API de facturation sont encore expérimentales. Épinglez vos versions des packages @clerk/nextjs et clerk-js. Voir la compétence clerk pour le tableau des versions prises en charge.

Démarrage rapide

  1. Activez la facturation, via Tableau de bord → Facturation → Paramètres ou clerk enable billing (voir section Agent-first). Ignorer cette étape lève une erreur cannot_render_billing_disabled en développement et rend un composant vide en production.

  2. Créez des plans dans l'onglet correspondant, Tableau de bord → Facturation → Plans. Deux onglets, slugs limités par onglet, non déplaçables après création :

    • Plans utilisateur → <PricingTable /> (par défaut for="user")
    • Plans d'organisation → <PricingTable for="organization" />

    Un mauvais onglet est la cause n°1 d'un <PricingTable /> vide. Les plans résident dans Clerk ; ils ne sont pas synchronisés avec Stripe.

  3. Ajoutez des fonctionnalités dans un plan, ouvrez le plan dans le Tableau de bord → Facturation → Plans, utilisez sa section Fonctionnalités. Les fonctionnalités sont limitées à chaque plan, pas globales. Le même slug peut être attaché à plusieurs plans ; has({ feature: 'export' }) correspond si le plan actif contient ce slug.

  4. Affichez <PricingTable /> (passez for="organization" pour le B2B).

  5. Contrôlez l'accès avec has({ plan }) ou has({ feature }) depuis auth().

  6. Gérez les webhooks de facturation pour le cycle de vie des abonnements.

Raccourcis du tableau de bord

ActionURL
Activer la facturationhttps://dashboard.clerk.com/last-active?path=billing/settings
Créer / modifier des planshttps://dashboard.clerk.com/last-active?path=billing/plans
Mode d'adhésion (coexistence B2C + B2B)https://dashboard.clerk.com/last-active?path=organizations-settings
Modifier les fonctionnalitésPlans → cliquer sur un plan → section Fonctionnalités (pas d'URL directe)

Agent-first : Configuration de facturation programmatique

La configuration complète de la facturation (interrupteurs d'activation, plans, fonctionnalités, liaisons plan-fonctionnalité) est modifiable via PLAPI sans toucher au tableau de bord. Utile pour les agents qui créent des plans, répliquent la configuration entre instances ou contrôlent la version de la structure de facturation.

Prérequis : projet lié à l'application Clerk (clerk auth login + clerk link, voir clerk-setup).

Activer la facturation via CLI

clerk enable billing                # les deux cibles (par défaut, crée automatiquement free_user + free_org plans)
clerk enable billing --for org      # organisation uniquement
clerk enable billing --for user     # utilisateur uniquement

Récupérer la configuration de facturation actuelle

clerk config pull --keys billing > billing.json

Cela écrit la configuration de facturation actuelle (interrupteurs + plans + fonctionnalités) pour l'instance liée dans billing.json.

Modifier et appliquer

Modifiez billing.json pour ajouter ou supprimer des plans ou fonctionnalités, puis prévisualisez la différence et appliquez-la :

clerk config patch --file billing.json --dry-run
clerk config patch --file billing.json

Passez --instance prod pour cibler l'instance de production au lieu de l'instance de développement.

PATCH brut (contrôle total)

Pour des mises à jour ponctuelles de plan/fonctionnalité sans fichier de configuration :

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"}]}}'

Remarques

  • Cela gère la configuration de facturation (interrupteurs + catalogue de plans et fonctionnalités). Le cycle de vie des abonnements (les utilisateurs choisissant un plan, le paiement, le renouvellement, l'annulation) passe toujours par <PricingTable /> + les webhooks de facturation, voir la compétence clerk-webhooks pour les événements du cycle de vie.
  • La manipulation de la carte features de niveau supérieur et les liaisons plan-fonctionnalité (synchronisation) sont entièrement prises en charge via le gestionnaire de configuration de facturation PLAPI.

De quoi avez-vous besoin ?

TâcheRéférence
Props de <PricingTable />, <CheckoutButton />, modèles de facturation <Show>references/billing-components.md
Modèles B2C (abonnements utilisateur individuels, prérequis « Adhésion optionnelle »)references/b2c-patterns.md
Modèles B2B (abonnements d'organisation, plans à sièges, interface de facturation gérée par l'admin)references/b2b-patterns.md
Catalogue d'événements webhook, structures de charge utile, modèles de gestionnairesreferences/billing-webhooks.md

Références

RéférenceDescription
references/billing-components.md<PricingTable /> et interface utilisateur d'abonnement
references/b2c-patterns.mdModèles de facturation d'abonnement B2C
references/b2b-patterns.mdFacturation B2B avec abonnements d'organisation et plans à sièges
references/billing-webhooks.mdGestion des événements du cycle de vie des abonnements

Documentation

Fonctionnalités vs Plans : Quand utiliser quoi

Utilisez has({ feature: 'slug' }) pour contrôler l'accès à une capacité spécifique, export, analytiques, accès API, journaux d'audit.

Utilisez has({ plan: 'slug' }) pour contrôler l'accès à un niveau, afficher le tableau de bord pro, vérifier le niveau d'abonnement de l'organisation, rediriger les utilisateurs gratuits.

ScénarioVérification correcte
Contrôler l'accès au bouton « Exporter CSV »has({ feature: 'export' })
Contrôler l'accès à la section « Analytiques »has({ feature: 'analytics' })
Contrôler l'accès à tout /dashboard/prohas({ plan: 'pro' })
Vérifier si l'organisation a un abonnement équipehas({ plan: 'org:team' })
Contrôler l'accès à la configuration SSOhas({ feature: 'sso' })

Lorsqu'un utilisateur dit « contrôle l'accès à la fonctionnalité d'exportation » ou « contrôle l'accès aux analytiques », utilisez toujours has({ feature }). N'utilisez has({ plan }) que lorsque le contrôle concerne le niveau du plan lui-même, pas une capacité spécifique à l'intérieur de celui-ci.

Modèles clés

1. Afficher le tableau des prix

Affichez les plans disponibles aux utilisateurs avec un seul composant :

import { PricingTable } from '@clerk/nextjs'

export default function PricingPage() {
	return (
		<main>
			<h1>Choisissez un plan</h1>
			<PricingTable />
		</main>
	)
}

<PricingTable /> affiche automatiquement tous les plans configurés dans le tableau de bord Clerk. La sélection d'un plan ouvre le tiroir de paiement intégré de Clerk. Aucune prop nécessaire pour une utilisation de base. Pour le B2B, passez for="organization" pour afficher les plans d'organisation au lieu des plans utilisateur.

2. Vérifier les droits d'accès aux fonctionnalités (côté serveur)

Contrôlez l'accès par fonctionnalités individuelles, c'est l'approche préférée pour les capacités spécifiques :

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>
	)
}

Les fonctionnalités sont configurées dans Tableau de bord Clerk → Facturation → Fonctionnalités et attribuées aux plans. Utilisez has({ feature }) au lieu de has({ plan }) pour contrôler l'accès à des capacités granulaires, vérifiez la fonctionnalité, pas le plan.

3. Vérifier les droits d'accès aux fonctionnalités (côté client)

Utilisez useAuth() pour le contrôle d'accès côté client. Combinez avec les vérifications côté serveur pour une couverture complète :

'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>
	)
}

Les composants serveur utilisent auth(), les composants client utilisent useAuth(). Les deux prennent en charge has({ feature }) et has({ plan }).

4. Vérifier le plan d'abonnement côté serveur

Contrôlez l'accès par plan d'abonnement (utilisez ceci pour les contrôles de niveau, pas pour les fonctionnalités individuelles) :

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. Vérifications de plan côté client

Utilisez le hook useAuth() pour les composants client :

'use client'
import { useAuth } from '@clerk/nextjs'

export function UpgradePrompt() {
	const { has } = useAuth()

	if (has?.({ plan: 'pro' })) {
		return null
	}

	return (
		<div>
			<p>Passez à Pro pour accéder à cette fonctionnalité</p>
			<a href="/pricing">Voir les plans</a>
		</div>
	)
}

6. Facturation B2B basée sur les sièges avec les organisations

Les plans d'organisation peuvent comporter une limite de sièges (plafond d'adhésion) que Clerk applique au moment de l'invitation. Utilisez le préfixe de slug org: pour les vérifications de plan côté organisation (ex. has({ plan: 'org:team' })) pour garder un contrôle d'accès sans ambiguïté. Affichez la page de tarification B2B avec <PricingTable for="organization" />, et utilisez <OrganizationProfile /> pour l'interface utilisateur de facturation du compte d'organisation.

Voir references/b2b-patterns.md pour la dénomination des plans à plusieurs niveaux, les invariants de limite de sièges, la facturation réservée aux administrateurs et les gestionnaires de webhooks.

7. Afficher le statut de l'abonnement

Vérifiez des plans spécifiques avec has({ plan }), ou utilisez useSubscription() pour obtenir les détails complets de l'abonnement dans les composants client. Ne lisez pas les informations du plan directement depuis sessionClaims, ce n'est pas le chemin pris en charge.

Composant serveur, vérifiez des plans spécifiques :

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 actuel</h2>
			<p>Vous êtes sur le plan {currentPlan}</p>
			{currentPlan === 'free' && <a href="/pricing">Passer à la version supérieure</a>}
		</div>
	)
}

Composant client, détails complets de l'abonnement 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">Choisissez un plan</a>

	return (
		<div>
			<p>Statut : {subscription.status}</p>
			{subscription.nextPayment && (
				<p>Prochain paiement : {subscription.nextPayment.date.toLocaleDateString()}</p>
			)}
		</div>
	)
}

useSubscription() est uniquement pour l'affichage. Pour les vérifications d'autorisation (contrôle d'accès au contenu ou aux routes), utilisez toujours has({ plan }) ou has({ feature }).

8. Protéger les routes d'API par plan

Contrôlez l'accès aux routes d'API à l'aide de 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: 'Plan Pro requis' }, { status: 403 })
	}

	return NextResponse.json({ data: 'données premium' })
}

9. Gérer les webhooks de facturation

Les noms d'événements Clerk diffèrent des noms d'événements Stripe. Les webhooks de facturation Clerk utilisent la notation par points et le camelCase, pas le format de soulignement de Stripe.

Il n'y a pas d'événement subscription.canceled. L'annulation se déclenche au niveau de l'élément en tant que subscriptionItem.canceled.

IntentionNom d'événement StripeNom d'événement Clerk
Abonnement créécustomer.subscription.createdsubscription.created
Abonnement mis à jourcustomer.subscription.updatedsubscription.updated
Abonnement actif(aucun)subscription.active
Abonnement en retard(aucun)subscription.pastDue
Élément d'abonnement annulécustomer.subscription.deletedsubscriptionItem.canceled
Élément d'abonnement en retardinvoice.payment_failedsubscriptionItem.pastDue
Élément d'abonnement mis à jour(aucun)subscriptionItem.updated
Élément d'abonnement actif(aucun)subscriptionItem.active
Renouvellement à venir d'un élément d'abonnement(aucun)subscriptionItem.upcoming
Élément d'abonnement terminé(aucun)subscriptionItem.ended
Élément d'abonnement abandonné(aucun)subscriptionItem.abandoned
Élément d'abonnement expiré(aucun)subscriptionItem.expired
Élément d'abonnement incomplet(aucun)subscriptionItem.incomplete
Essai gratuit bientôt terminé(aucun)subscriptionItem.freeTrialEnding
Tentative de paiement créée(aucun)paymentAttempt.created
Tentative de paiement mise à jour(aucun)paymentAttempt.updated

Utilisez toujours les noms d'événements Clerk, jamais ceux de Stripe, dans les vérifications evt.type.

Structure de la charge utile. Les charges utiles des webhooks de facturation Clerk sont imbriquées. L'entité abonnée se trouve sous evt.data.payer (champs : user_id?, organization_id?). Les informations du plan sont sur chaque élément sous evt.data.items[i].plan.slug. L'identifiant de l'abonnement est simplement evt.data.id. Les éléments d'abonnement n'ont pas de champ subscription_id de référence arrière, donc dans les gestionnaires subscriptionItem.*, vous identifiez l'enregistrement par l'ID de l'élément (evt.data.id) ou recherchez par payeur plus plan.

Gestionnaire minimal pour ancrer le modèle (importer depuis @clerk/nextjs/webhooks, vérifier, bifurquer sur le nom d'événement 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('Échec de la vérification', { status: 400 })
	}

	if (evt.type === 'subscription.created') {
		const { id, payer, items, status } = evt.data
		const entityId = payer.user_id || payer.organization_id
		// TODO : enregistrer l'abonnement
	}

	if (evt.type === 'subscriptionItem.canceled') {
		const { id, item, payer } = evt.data
		// TODO : mettre à jour le statut de l'élément d'abonnement
	}

	return new Response('OK', { status: 200 })
}

Bonnes pratiques

  • Vérifications côté serveur : utilisez toujours auth().has() dans les composants serveur et les routes d'API comme source de vérité pour l'autorisation.
  • Vérifications côté client : utilisez useAuth().has() pour l'interface utilisateur réactive (afficher/masquer des éléments).
  • Fonctionnalités vs Plans : utilisez has({ feature: 'slug' }) pour les capacités granulaires, has({ plan: 'slug' }) pour les contrôles de niveau entier.
  • Informations sur le plan : utilisez has({ plan }) ou useSubscription() pour les détails de l'abonnement ; ne lisez pas depuis sessionClaims.
  • Développement : les instances de développement n'ont pas besoin de Stripe, utilisez la passerelle partagée Clerk pour tester les flux de paiement.
  • Webhooks : utilisez les noms d'événements Clerk (pas Stripe) ; gérez les événements de cycle de vie pour la synchronisation des abonnements.

Problèmes courants

ProblèmeCause probableSolution
<PricingTable /> videAucun plan configuré dans l'onglet correspondant (utilisateur vs organisation)Vérifiez que les plans existent dans Tableau de bord → Facturation → Plans et que vous utilisez le bon onglet
cannot_render_billing_disabledLa facturation n'est pas activéeActivez via le tableau de bord ou clerk enable billing
has({ feature: 'x' }) renvoie toujours falseLa fonctionnalité n'est pas assignée au plan actuel de l'utilisateurVérifiez les assignations de fonctionnalités dans le plan
Le webhook ne se déclenche pasMauvaise configuration du point de terminaison ou mauvaise vérification du type d'événementVérifiez que vous utilisez evt.type avec les noms d'événements Clerk, pas Stripe

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 associés