Facturation
ARRÊTEZ-VOUS, prérequis. La facturation doit être activée avant toute utilisation de
<PricingTable />,<CheckoutButton />,has({ plan })ouhas({ 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éfautfree_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/nextjsetclerk-js. Voir la compétenceclerkpour le tableau des versions prises en charge.
Démarrage rapide
-
Activez la facturation, via Tableau de bord → Facturation → Paramètres ou
clerk enable billing(voir section Agent-first). Ignorer cette étape lève une erreurcannot_render_billing_disableden développement et rend un composant vide en production. -
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éfautfor="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. - Plans utilisateur →
-
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. -
Affichez
<PricingTable />(passezfor="organization"pour le B2B). -
Contrôlez l'accès avec
has({ plan })ouhas({ feature })depuisauth(). -
Gérez les webhooks de facturation pour le cycle de vie des abonnements.
Raccourcis du tableau de bord
| Action | URL |
|---|---|
| Activer la facturation | https://dashboard.clerk.com/last-active?path=billing/settings |
| Créer / modifier des plans | https://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és | Plans → 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étenceclerk-webhookspour les événements du cycle de vie. - La manipulation de la carte
featuresde 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âche | Ré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 gestionnaires | references/billing-webhooks.md |
Références
| Référence | Description |
|---|---|
references/billing-components.md | <PricingTable /> et interface utilisateur d'abonnement |
references/b2c-patterns.md | Modèles de facturation d'abonnement B2C |
references/b2b-patterns.md | Facturation B2B avec abonnements d'organisation et plans à sièges |
references/billing-webhooks.md | Gestion 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énario | Vé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/pro | has({ plan: 'pro' }) |
| Vérifier si l'organisation a un abonnement équipe | has({ plan: 'org:team' }) |
| Contrôler l'accès à la configuration SSO | has({ 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 toujourshas({ plan })ouhas({ 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 quesubscriptionItem.canceled.
Intention Nom d'événement Stripe Nom d'événement Clerk Abonnement créé customer.subscription.createdsubscription.createdAbonnement mis à jour customer.subscription.updatedsubscription.updatedAbonnement actif (aucun) subscription.activeAbonnement en retard (aucun) subscription.pastDueÉlément d'abonnement annulé customer.subscription.deletedsubscriptionItem.canceledÉlément d'abonnement en retard invoice.payment_failedsubscriptionItem.pastDueÉlément d'abonnement mis à jour (aucun) subscriptionItem.updatedÉlément d'abonnement actif (aucun) subscriptionItem.activeRenouvellement à 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.incompleteEssai gratuit bientôt terminé (aucun) subscriptionItem.freeTrialEndingTentative de paiement créée (aucun) paymentAttempt.createdTentative de paiement mise à jour (aucun) paymentAttempt.updatedUtilisez 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 sousevt.data.items[i].plan.slug. L'identifiant de l'abonnement est simplementevt.data.id. Les éléments d'abonnement n'ont pas de champsubscription_idde référence arrière, donc dans les gestionnairessubscriptionItem.*, 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 })ouuseSubscription()pour les détails de l'abonnement ; ne lisez pas depuissessionClaims. - 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ème | Cause probable | Solution |
|---|---|---|
<PricingTable /> vide | Aucun 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_disabled | La facturation n'est pas activée | Activez via le tableau de bord ou clerk enable billing |
has({ feature: 'x' }) renvoie toujours false | La fonctionnalité n'est pas assignée au plan actuel de l'utilisateur | Vérifiez les assignations de fonctionnalités dans le plan |
| Le webhook ne se déclenche pas | Mauvaise configuration du point de terminaison ou mauvaise vérification du type d'événement | Vérifiez que vous utilisez evt.type avec les noms d'événements Clerk, pas Stripe |