Abrechnung
STOPP, Voraussetzung. Die Abrechnung muss aktiviert sein, bevor
<PricingTable />,<CheckoutButton />,has({ plan })oderhas({ feature })verwendet werden können. Zwei Wege: (1) Dashboard → Abrechnung → Einstellungen, oder (2)clerk enable billing(siehe "Agent-first: Programmatische Abrechnungskonfiguration" unten). Die Aktivierung erstellt automatisch die Standardplänefree_user/free_org. Dev-Instanzen können das gemeinsame Clerk-Entwicklungsgateway verwenden (kein Stripe-Konto erforderlich); die Produktion erfordert ein Stripe-Konto nur für die Zahlungsabwicklung.Hinweis: Die Abrechnungs-APIs sind noch experimentell. Sichern Sie Ihre Versionen von
@clerk/nextjsundclerk-js. Sieheclerk-Skill für die unterstützte Versionstabelle.
Kurzanleitung
-
Abrechnung aktivieren, via Dashboard → Abrechnung → Einstellungen oder
clerk enable billing(siehe Abschnitt Agent-first). Das Überspringen führt in der Entwicklung zucannot_render_billing_disabledund in der Produktion zu einer leeren Ansicht. -
Pläne im passenden Tab erstellen, Dashboard → Abrechnung → Pläne. Zwei Tabs, Slugs sind pro Tab begrenzt, nach der Erstellung nicht verschiebbar:
- Benutzerpläne →
<PricingTable />(Standardfor="user") - Organisationspläne →
<PricingTable for="organization" />
Der falsche Tab ist die häufigste Ursache für ein leeres
<PricingTable />. Pläne leben in Clerk; nicht mit Stripe synchronisiert. - Benutzerpläne →
-
Funktionen innerhalb eines Plans hinzufügen, öffnen Sie den Plan im Dashboard → Abrechnung → Pläne, nutzen Sie den Bereich "Funktionen". Funktionen sind pro Plan begrenzt, nicht global. Derselbe Slug kann mehreren Plänen zugeordnet werden;
has({ feature: 'export' })trifft zu, wenn der aktive Plan diesen Slug enthält. -
<PricingTable />rendern (übergeben Siefor="organization"für B2B). -
Zugriff steuern mit
has({ plan })oderhas({ feature })ausauth(). -
Abrechnungs-Webhooks behandeln für den Abonnement-Lebenszyklus.
Dashboard-Shortcuts
| Aktion | URL |
|---|---|
| Abrechnung aktivieren | https://dashboard.clerk.com/last-active?path=billing/settings |
| Pläne erstellen / bearbeiten | https://dashboard.clerk.com/last-active?path=billing/plans |
| Mitgliedschaftsmodus (B2C + B2B-Koexistenz) | https://dashboard.clerk.com/last-active?path=organizations-settings |
| Funktionen bearbeiten | Pläne → Klicken Sie auf einen Plan → Bereich "Funktionen" (keine direkte URL) |
Agent-first: Programmatische Abrechnungskonfiguration
Die vollständige Abrechnungskonfiguration (Aktivierungsumschalter, Pläne, Funktionen, Plan-Funktions-Zuordnungen) ist über PLAPI bearbeitbar, ohne das Dashboard zu berühren. Nützlich für Agenten, die Pläne anlegen, Konfigurationen über Instanzen replizieren oder die Abrechnungsstruktur versionieren.
Voraussetzung: Projekt mit der Clerk-App verknüpft (clerk auth login + clerk link, siehe clerk-setup).
Abrechnung via CLI aktivieren
clerk enable billing # beide Ziele (Standard, erstellt automatisch free_user + free_org-Pläne)
clerk enable billing --for org # nur Organisation
clerk enable billing --for user # nur Benutzer
Aktuelle Abrechnungskonfiguration abrufen
clerk config pull --keys billing > billing.json
Dies schreibt die aktuelle Abrechnungskonfiguration (Umschalter + Pläne + Funktionen) für die verknüpfte Instanz in billing.json.
Bearbeiten und anwenden
Bearbeiten Sie billing.json, um Pläne oder Funktionen hinzuzufügen/zu entfernen, zeigen Sie dann den Diff an und wenden Sie ihn an:
clerk config patch --file billing.json --dry-run
clerk config patch --file billing.json
Übergeben Sie --instance prod, um die Produktionsinstanz statt der Dev-Instanz anzusprechen.
Raw PATCH (volle Kontrolle)
Für einmalige Plan-/Funktionsaktualisierungen ohne Konfigurationsdatei:
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"}]}}'
Hinweise
- Dies behandelt die Abrechnungskonfiguration (Umschalter + Pläne + Funktionskatalog). Der Abonnement-Lebenszyklus (Benutzer wählen einen Plan, Checkout, Verlängerung, Kündigung) läuft weiterhin über
<PricingTable />+ Abrechnungs-Webhooks, sieheclerk-webhooks-Skill für die Lebenszyklus-Ereignisse. - Die Manipulation des Top-Level-
features-Maps und Plan-Funktions-Zuordnungen (Sync) werden vollständig über den PLAPI-Abrechnungskonfigurations-Handler unterstützt.
Was brauchen Sie?
| Aufgabe | Referenz |
|---|---|
<PricingTable />-Props, <CheckoutButton />, <Show>-Abrechnungsmuster | references/billing-components.md |
B2C-Muster (einzelne Benutzerabos, vorausgesetzte Membership optional) | references/b2c-patterns.md |
| B2B-Muster (Organisationsabos, Sitzungsbeschränkungspläne, admin-gesteuerte Abrechnungs-UI) | references/b2b-patterns.md |
| Webhook-Ereigniskatalog, Payload-Formate, Handler-Vorlagen | references/billing-webhooks.md |
Referenzen
| Referenz | Beschreibung |
|---|---|
references/billing-components.md | <PricingTable /> und Abonnement-UI |
references/b2c-patterns.md | B2C-Abonnement-Abrechnungsmuster |
references/b2b-patterns.md | B2B-Abrechnung mit Organisationsabos und Sitzungsbeschränkungsplänen |
references/billing-webhooks.md | Ereignisbehandlung des Abonnement-Lebenszyklus |
Dokumentation
Funktionen vs. Pläne: Wann verwenden Sie was
Verwenden Sie has({ feature: 'slug' }), wenn Sie eine bestimmte Fähigkeit sperren, Export, Analysen, API-Zugriff, Audit-Logs.
Verwenden Sie has({ plan: 'slug' }), wenn Sie eine Stufe sperren, das Pro-Dashboard anzeigen, die Organisations-Abonnementstufe prüfen, kostenlose Benutzer umleiten.
| Szenario | Korrekte Prüfung |
|---|---|
| "Export CSV"-Button sperren | has({ feature: 'export' }) |
| "Analysen"-Abschnitt sperren | has({ feature: 'analytics' }) |
| Alle von /dashboard/pro sperren | has({ plan: 'pro' }) |
| Prüfen, ob die Organisation ein Team-Abo hat | has({ plan: 'org:team' }) |
| SSO-Konfiguration sperren | has({ feature: 'sso' }) |
Wenn ein Benutzer sagt "sperre die Export-Funktion" oder "sperre die Analysen", verwenden Sie immer has({ feature }). Verwenden Sie has({ plan }) nur, wenn die Sperre die Planstufe selbst ist, nicht eine bestimmte Fähigkeit darin.
Schlüsselmuster
1. Preistabelle rendern
Zeigen Sie Benutzern verfügbare Pläne mit einer einzigen Komponente an:
import { PricingTable } from '@clerk/nextjs'
export default function PricingPage() {
return (
<main>
<h1>Wählen Sie einen Plan</h1>
<PricingTable />
</main>
)
}
<PricingTable /> rendert automatisch alle konfigurierten Pläne aus dem Clerk-Dashboard. Die Auswahl eines Plans öffnet den In-App-Checkout-Drawer von Clerk. Keine Props für die Basisnutzung erforderlich. Für B2B übergeben Sie for="organization", um organisationsspezifische Pläne statt Benutzerpläne anzuzeigen.
2. Feature-Berechtigungen prüfen (serverseitig)
Sperren Sie nach einzelnen Funktionen, dies ist der bevorzugte Ansatz für spezifische Fähigkeiten:
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>
)
}
Funktionen werden im Clerk-Dashboard → Abrechnung → Funktionen konfiguriert und Plänen zugewiesen. Verwenden Sie has({ feature }) anstelle von has({ plan }), wenn Sie granulare Fähigkeiten sperren – prüfen Sie die Funktion, nicht den Plan.
3. Feature-Berechtigungen prüfen (clientseitig)
Verwenden Sie useAuth() für clientseitiges Feature-Gating. Kombinieren Sie es mit serverseitigen Prüfungen für vollständige Abdeckung:
'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>
)
}
Server-Komponenten verwenden auth(), Client-Komponenten verwenden useAuth(). Beide unterstützen has({ feature }) und has({ plan }).
4. Abonnementplan serverseitig prüfen
Sperren Sie den Zugriff nach Abonnementplan (verwenden Sie dies für stufenbezogene Sperren, nicht für einzelne Funktionen):
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. Clientseitige Planprüfungen
Verwenden Sie den useAuth()-Hook für Client-Komponenten:
'use client'
import { useAuth } from '@clerk/nextjs'
export function UpgradePrompt() {
const { has } = useAuth()
if (has?.({ plan: 'pro' })) {
return null
}
return (
<div>
<p>Upgraden Sie auf Pro, um auf diese Funktion zuzugreifen</p>
<a href="/pricing">Pläne anzeigen</a>
</div>
)
}
6. B2B-Sitzungsbasierte Abrechnung mit Organisationen
Organisationspläne können ein Sitzungslimit (Mitgliederbeschränkung) enthalten, das Clerk bei der Einladung durchsetzt. Verwenden Sie das org:-Slug-Präfix bei organisationsseitigen Planprüfungen (z. B. has({ plan: 'org:team' })), um das Gating eindeutig zu halten. Rendern Sie die B2B-Preisseite mit <PricingTable for="organization" /> und verwenden Sie <OrganizationProfile /> für die Organisations-Abrechnungs-UI.
Siehe references/b2b-patterns.md für gestaffelte Planbenennung, Sitzungslimit-Invarianten, Admin-only-Abrechnung und Webhook-Handler.
7. Abonnementstatus anzeigen
Prüfen Sie bestimmte Pläne mit has({ plan }), oder verwenden Sie useSubscription() für vollständige Abonnementdetails in Client-Komponenten. Lesen Sie Planinformationen nicht direkt aus sessionClaims, das ist nicht der unterstützte Weg.
Server-Komponente, Prüfung auf bestimmte Pläne:
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>Aktueller Plan</h2>
<p>Sie sind im {currentPlan}-Plan</p>
{currentPlan === 'free' && <a href="/pricing">Upgraden</a>}
</div>
)
}
Client-Komponente, vollständige Abonnementdetails 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">Plan wählen</a>
return (
<div>
<p>Status: {subscription.status}</p>
{subscription.nextPayment && (
<p>Nächste Zahlung: {subscription.nextPayment.date.toLocaleDateString()}</p>
)}
</div>
)
}
useSubscription()dient nur der Anzeige. Für Autorisierungsprüfungen (Sperren von Inhalten oder Routen) verwenden Sie immerhas({ plan })oderhas({ feature }).
8. API-Routen nach Plan schützen
Sperren Sie API-Routen mit 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: 'Pro-Plan erforderlich' }, { status: 403 })
}
return NextResponse.json({ data: 'premium data' })
}
9. Abrechnungs-Webhooks behandeln
Clerk-Ereignisnamen unterscheiden sich von Stripe-Ereignisnamen. Clerk-Abrechnungs-Webhooks verwenden Punktnotation und camelCase, nicht das Unterstrichensformat von Stripe.
Es gibt kein
subscription.canceled-Ereignis. Die Kündigung erfolgt auf Elementebene alssubscriptionItem.canceled.
Absicht Stripe-Ereignisname Clerk-Ereignisname Abonnement erstellt customer.subscription.createdsubscription.createdAbonnement aktualisiert customer.subscription.updatedsubscription.updatedAbonnement aktiv (keines) subscription.activeAbonnement überfällig (keines) subscription.pastDueAbonnement-Element gekündigt customer.subscription.deletedsubscriptionItem.canceledAbonnement-Element überfällig invoice.payment_failedsubscriptionItem.pastDueAbonnement-Element aktualisiert (keines) subscriptionItem.updatedAbonnement-Element aktiv (keines) subscriptionItem.activeAbonnement-Element bevorstehende Verlängerung (keines) subscriptionItem.upcomingAbonnement-Element beendet (keines) subscriptionItem.endedAbonnement-Element aufgegeben (keines) subscriptionItem.abandonedAbonnement-Element abgelaufen (keines) subscriptionItem.expiredAbonnement-Element unvollständig (keines) subscriptionItem.incompleteKostenlose Testversion endet bald (keines) subscriptionItem.freeTrialEndingZahlungsversuch erstellt (keines) paymentAttempt.createdZahlungsversuch aktualisiert (keines) paymentAttempt.updatedVerwenden Sie immer Clerk-Ereignisnamen, niemals Stripe, in
evt.type-Prüfungen.
Payload-Format. Clerk-Abrechnungs-Webhook-Payloads sind verschachtelt. Die abonnierende Entität befindet sich unter
evt.data.payer(Felder:user_id?,organization_id?). Die Planinformationen befinden sich auf jedem Element unterevt.data.items[i].plan.slug. Die Abonnement-ID ist einfachevt.data.id. Abonnement-Elemente haben keinsubscription_id-Feld als Rückverweis, daher identifizieren Sie insubscriptionItem.*-Handlern den Datensatz durch die Element-ID (evt.data.id) oder suchen nach Zahler plus Plan.
Minimaler Handler zur Verankerung des Musters (importieren von @clerk/nextjs/webhooks, verifizieren, nach Clerk-Ereignisnamen verzweigen):
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('Verifizierung fehlgeschlagen', { status: 400 })
}
if (evt.type === 'subscription.created') {
const { id, payer, items, status } = evt.data
const entityId = p
…