[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7A4ZHS402BGMWNSCBCVAAVH":3,"skill-same:01M7A4ZHS402BGMWNSCBCVAAVH":70},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":27,"commitSha":28,"skillDirectory":29,"forksCount":14,"repositoryHtmlUrl":30,"repositoryHomepageUrl":6,"ownerHtmlUrl":31,"ownerBlogUrl":6,"ownerDescription":32,"updatedAt":33,"install":34,"resources":47},"01M7A4ZHS402BGMWNSCBCVAAVH","clerk-billing",null,"Clerk Billing for subscription management - render Clerk's PricingTable and in-app checkout drawer, configure subscription plans, seat-limit plans for B2B, feature entitlements with has(), and billing webhooks. Use for SaaS monetization, plan gating, checkout flows, trials, invoicing, and subscription lifecycle management.","NeelakshSaxena\u002FVayu","NeelakshSaxena","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F87892838?v=4","01M7A3B9YFS6F6N9DD1787DT86","Neelaksh Saxena","01M7A3B9ZKBT09MNMPX2XN69BY",0,"MIT","https:\u002F\u002Fgithub.com\u002FNeelakshSaxena\u002FVayu\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fclerk-billing\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\ndescription: \"Clerk Billing for subscription management - render Clerk's PricingTable and in-app checkout drawer, configure subscription plans, seat-limit plans for B2B, feature entitlements with has(), and billing webhooks. Use for SaaS monetization, plan gating, checkout flows, trials, invoicing, and subscription lifecycle management.\"\nlicense: \"MIT\"\nmetadata: {\"author\":\"clerk\",\"version\":\"1.1.0\"}\n---\n# Billing\n\n> **STOP, prerequisite.** Billing must be enabled before any `\u003CPricingTable \u002F>`, `\u003CCheckoutButton \u002F>`, `has({ plan })`, or `has({ feature })` usage works. Two paths: (1) [Dashboard → Billing → Settings](https:\u002F\u002Fdashboard.clerk.com\u002Flast-active?path=billing\u002Fsettings), or (2) `clerk enable billing` (see \"Agent-first: Programmatic billing config\" below). Enabling auto-creates default `free_user` \u002F `free_org` plans. Dev instances can use the shared Clerk development gateway (no Stripe account needed); production requires a Stripe account for payment processing only.\n>\n> **Note**: Billing APIs are still experimental. Pin your `@clerk\u002Fnextjs` and `clerk-js` package versions. See `clerk` skill for the supported version table.\n\n## Quick Start\n\n1. **Enable Billing**, via [Dashboard → Billing → Settings](https:\u002F\u002Fdashboard.clerk.com\u002Flast-active?path=billing\u002Fsettings) or `clerk enable billing` (see Agent-first section). Skipping this throws `cannot_render_billing_disabled` in dev and renders empty in prod.\n2. **Create plans in the matching tab**, [Dashboard → Billing → Plans](https:\u002F\u002Fdashboard.clerk.com\u002Flast-active?path=billing\u002Fplans). Two tabs, slugs scoped per tab, not movable after creation:\n   - **User Plans** → `\u003CPricingTable \u002F>` (default `for=\"user\"`)\n   - **Organization Plans** → `\u003CPricingTable for=\"organization\" \u002F>`\n\n   Wrong-tab is the #1 cause of an empty `\u003CPricingTable \u002F>`. Plans live in Clerk; not synced to Stripe.\n3. **Add features inside a plan**, open the plan in Dashboard → Billing → Plans, use its Features section. Features are scoped per plan, not global. The same slug can attach to multiple plans; `has({ feature: 'export' })` matches if the active plan contains that slug.\n4. **Render `\u003CPricingTable \u002F>`** (pass `for=\"organization\"` for B2B).\n5. **Gate access** with `has({ plan })` or `has({ feature })` from `auth()`.\n6. **Handle billing webhooks** for subscription lifecycle.\n\n## Dashboard shortcuts\n\n| Action | URL |\n|---|---|\n| Enable Billing | `https:\u002F\u002Fdashboard.clerk.com\u002Flast-active?path=billing\u002Fsettings` |\n| Create \u002F edit plans | `https:\u002F\u002Fdashboard.clerk.com\u002Flast-active?path=billing\u002Fplans` |\n| Membership mode (B2C + B2B coexistence) | `https:\u002F\u002Fdashboard.clerk.com\u002Flast-active?path=organizations-settings` |\n| Edit features | Plans → click a plan → Features section (no direct URL) |\n\n## Agent-first: Programmatic billing config\n\nThe full billing config (enable toggles, plans, features, plan-feature attachments) is editable via PLAPI without touching the Dashboard. Useful for agents seeding plans, replicating config across instances, or version-controlling billing structure.\n\nPre-req: project linked to the Clerk app (`clerk auth login` + `clerk link`, see `clerk-setup`). Billing is account-only — unlike orgs, it cannot be enabled on an unclaimed app; claim the app first.\n\n### Enable Billing via CLI\n\n```bash\nclerk enable billing                # both targets (default, auto-creates free_user + free_org plans)\nclerk enable billing --for org      # org only\nclerk enable billing --for user     # user only\n```\n\n### Pull current billing config\n\n```bash\nclerk config pull --keys billing > billing.json\n```\n\nThis writes the current billing config (toggles + plans + features) for the linked instance to `billing.json`.\n\n### Edit and apply\n\nEdit `billing.json` to add\u002Fremove plans or features, then preview the diff and apply:\n\n```bash\nclerk config patch --file billing.json --dry-run\nclerk config patch --file billing.json\n```\n\nPass `--instance prod` to target the production instance instead of dev.\n\n### Raw PATCH (full control)\n\nFor one-shot plan\u002Ffeature updates without a config file:\n\n```bash\nclerk api --platform PATCH \u002Fv1\u002Fplatform\u002Fapplications\u002F\u003Capp_id>\u002Finstances\u002F\u003Cins_id>\u002Fconfig \\\n  -d '{\"billing\":{\"plans\":[{\"slug\":\"pro\",\"name\":\"Pro\",\"amount\":2000,\"currency\":\"usd\",\"payer_type\":\"user\",\"is_recurring\":true}],\"features\":[{\"slug\":\"export\",\"name\":\"Export\"}]}}'\n```\n\n### Notes\n\n- This handles **billing config** (toggles + plans + features catalog). **Subscription lifecycle** (users picking a plan, checkout, renewal, cancellation) still flows through `\u003CPricingTable \u002F>` + billing webhooks, see `clerk-webhooks` skill for the lifecycle events.\n- Top-level `features` map manipulation and plan-feature attachments (sync) are fully supported via the PLAPI billing config handler.\n\n## What Do You Need?\n\n| Task | Reference |\n|------|-----------|\n| `\u003CPricingTable \u002F>` props, `\u003CCheckoutButton \u002F>`, `\u003CShow>` billing patterns | references\u002Fbilling-components.md |\n| B2C patterns (individual user subscriptions, `Membership optional` prerequisite) | references\u002Fb2c-patterns.md |\n| B2B patterns (org subscriptions, seat-limit plans, admin-gated billing UI) | references\u002Fb2b-patterns.md |\n| Webhook event catalog, payload shapes, handler templates | references\u002Fbilling-webhooks.md |\n\n## References\n\n| Reference | Description |\n|-----------|-------------|\n| `references\u002Fbilling-components.md` | `\u003CPricingTable \u002F>` and subscription UI |\n| `references\u002Fb2c-patterns.md` | B2C subscription billing patterns |\n| `references\u002Fb2b-patterns.md` | B2B billing with organization subscriptions and seat-limit plans |\n| `references\u002Fbilling-webhooks.md` | Subscription lifecycle event handling |\n\n## Documentation\n\n- [Billing overview](https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fbilling\u002Foverview)\n- [B2B SaaS billing](https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fbilling\u002Ffor-b2b)\n- [B2C SaaS billing](https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fbilling\u002Ffor-b2c)\n- [Billing webhooks](https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fdevelopment\u002Fwebhooks\u002Fbilling)\n\n## Features vs Plans: When to Use Which\n\n**Use `has({ feature: 'slug' })` when gating a specific capability**, export, analytics, API access, audit logs.\n\n**Use `has({ plan: 'slug' })` when gating a tier**, showing the pro dashboard, checking org subscription level, redirecting free users.\n\n| Scenario | Correct check |\n|----------|---------------|\n| Gate the \"Export CSV\" button | `has({ feature: 'export' })` |\n| Gate the \"Analytics\" section | `has({ feature: 'analytics' })` |\n| Gate all of \u002Fdashboard\u002Fpro | `has({ plan: 'pro' })` |\n| Check if org has team subscription | `has({ plan: 'org:team' })` |\n| Gate SSO configuration | `has({ feature: 'sso' })` |\n\nWhen a user says \"gate the export feature\" or \"gate analytics\", always use `has({ feature })`. Only use `has({ plan })` when the gate is the plan tier itself, not a specific capability within it.\n\n## Key Patterns\n\n### 1. Render the Pricing Table\n\nShow available plans to users with a single component:\n\n```tsx\nimport { PricingTable } from '@clerk\u002Fnextjs'\n\nexport default function PricingPage() {\n\treturn (\n\t\t\u003Cmain>\n\t\t\t\u003Ch1>Choose a plan\u003C\u002Fh1>\n\t\t\t\u003CPricingTable \u002F>\n\t\t\u003C\u002Fmain>\n\t)\n}\n```\n\n`\u003CPricingTable \u002F>` automatically renders all plans configured in the Clerk Dashboard. Selecting a plan opens Clerk's in-app checkout drawer. No props needed for basic usage. For B2B, pass `for=\"organization\"` to render org-level plans instead of user plans.\n\n### 2. Check Feature Entitlements (Server-Side)\n\nGate by individual features, this is the preferred approach for specific capabilities:\n\n```typescript\nimport { auth } from '@clerk\u002Fnextjs\u002Fserver'\n\nexport default async function AnalyticsPage() {\n\tconst { has } = await auth()\n\n\tconst canViewAnalytics = has({ feature: 'analytics' })\n\tconst canExport = has({ feature: 'export' })\n\n\treturn (\n\t\t\u003Cdiv>\n\t\t\t{canViewAnalytics && \u003CAnalyticsChart \u002F>}\n\t\t\t{canExport && \u003CExportButton \u002F>}\n\t\t\u003C\u002Fdiv>\n\t)\n}\n```\n\nFeatures are configured in Clerk Dashboard → Billing → Features and assigned to plans. Use `has({ feature })` instead of `has({ plan })` when gating granular capabilities, check the feature, not the plan.\n\n### 3. Check Feature Entitlements (Client-Side)\n\nUse `useAuth()` for client-side feature gating. Combine with server-side checks for full coverage:\n\n```tsx\n'use client'\nimport { useAuth } from '@clerk\u002Fnextjs'\n\nexport function FeatureGatedUI() {\n\tconst { has, isLoaded } = useAuth()\n\tif (!isLoaded) return null\n\n\tconst canExport = has?.({ feature: 'export' })\n\tconst canAnalytics = has?.({ feature: 'analytics' })\n\n\treturn (\n\t\t\u003Cdiv>\n\t\t\t{canAnalytics && \u003CAnalyticsSection \u002F>}\n\t\t\t{canExport ? \u003CExportButton \u002F> : \u003CUpgradeToExport \u002F>}\n\t\t\u003C\u002Fdiv>\n\t)\n}\n```\n\nServer Components use `auth()`, Client Components use `useAuth()`. Both support `has({ feature })` and `has({ plan })`.\n\n### 4. Check Subscription Plan Server-Side\n\nGate access by subscription plan (use this for tier-level gates, not individual features):\n\n```typescript\nimport { auth } from '@clerk\u002Fnextjs\u002Fserver'\nimport { redirect } from 'next\u002Fnavigation'\n\nexport default async function ProDashboard() {\n\tconst { has } = await auth()\n\n\tif (!has({ plan: 'pro' })) {\n\t\tredirect('\u002Fpricing')\n\t}\n\n\treturn \u003CProFeatures \u002F>\n}\n```\n\n### 5. Client-Side Plan Checks\n\nUse `useAuth()` hook for client components:\n\n```tsx\n'use client'\nimport { useAuth } from '@clerk\u002Fnextjs'\n\nexport function UpgradePrompt() {\n\tconst { has } = useAuth()\n\n\tif (has?.({ plan: 'pro' })) {\n\t\treturn null\n\t}\n\n\treturn (\n\t\t\u003Cdiv>\n\t\t\t\u003Cp>Upgrade to Pro to access this feature\u003C\u002Fp>\n\t\t\t\u003Ca href=\"\u002Fpricing\">View plans\u003C\u002Fa>\n\t\t\u003C\u002Fdiv>\n\t)\n}\n```\n\n### 6. B2B Seat-Based Billing with Organizations\n\nOrg plans can carry a **seat limit** (membership cap) that Clerk enforces at invite time. Use the `org:` slug prefix on org-side plan checks (e.g. `has({ plan: 'org:team' })`) to keep gating unambiguous. Render the B2B pricing page with `\u003CPricingTable for=\"organization\" \u002F>`, and use `\u003COrganizationProfile \u002F>` for the org account billing UI.\n\nSee `references\u002Fb2b-patterns.md` for tiered plan naming, seat-limit invariants, admin-only billing, and webhook handlers.\n\n### 7. Display Subscription Status\n\nCheck specific plans with `has({ plan })`, or use `useSubscription()` for full subscription details in client components. Do not read plan information from `sessionClaims` directly, that is not the supported path.\n\nServer component, check for specific plans:\n\n```typescript\nimport { auth } from '@clerk\u002Fnextjs\u002Fserver'\n\nexport default async function AccountPage() {\n\tconst { has } = await auth()\n\n\tconst currentPlan = has({ plan: 'pro' })\n\t\t? 'pro'\n\t\t: has({ plan: 'starter' })\n\t\t\t? 'starter'\n\t\t\t: 'free'\n\n\treturn (\n\t\t\u003Cdiv>\n\t\t\t\u003Ch2>Current Plan\u003C\u002Fh2>\n\t\t\t\u003Cp>You are on the {currentPlan} plan\u003C\u002Fp>\n\t\t\t{currentPlan === 'free' && \u003Ca href=\"\u002Fpricing\">Upgrade\u003C\u002Fa>}\n\t\t\u003C\u002Fdiv>\n\t)\n}\n```\n\nClient component, full subscription details via `useSubscription()`:\n\n```tsx\n'use client'\nimport { useSubscription } from '@clerk\u002Fnextjs\u002Fexperimental'\n\nexport function SubscriptionDetails() {\n\tconst { data: subscription, isLoading } = useSubscription()\n\tif (isLoading) return null\n\tif (!subscription) return \u003Ca href=\"\u002Fpricing\">Choose a plan\u003C\u002Fa>\n\n\treturn (\n\t\t\u003Cdiv>\n\t\t\t\u003Cp>Status: {subscription.status}\u003C\u002Fp>\n\t\t\t{subscription.nextPayment && (\n\t\t\t\t\u003Cp>Next payment: {subscription.nextPayment.date.toLocaleDateString()}\u003C\u002Fp>\n\t\t\t)}\n\t\t\u003C\u002Fdiv>\n\t)\n}\n```\n\n> `useSubscription()` is for display only. For authorization checks (gating content or routes), always use `has({ plan })` or `has({ feature })`.\n\n### 8. Protect API Routes by Plan\n\nGate API routes using `auth()`:\n\n```typescript\nimport { auth } from '@clerk\u002Fnextjs\u002Fserver'\nimport { NextResponse } from 'next\u002Fserver'\n\nexport async function GET() {\n\tconst { has } = await auth()\n\n\tif (!has({ plan: 'pro' })) {\n\t\treturn NextResponse.json({ error: 'Pro plan required' }, { status: 403 })\n\t}\n\n\treturn NextResponse.json({ data: 'premium data' })\n}\n```\n\n### 9. Handle Billing Webhooks\n\n> **Clerk event names differ from Stripe event names.** Clerk billing webhooks use dot-notation and camelCase, not Stripe's underscore format.\n>\n> There is no `subscription.canceled` event. Cancellation fires at the item level as `subscriptionItem.canceled`.\n>\n> | Intent | Stripe event name | Clerk event name |\n> |--------|------------------|-----------------|\n> | Subscription created | `customer.subscription.created` | `subscription.created` |\n> | Subscription updated | `customer.subscription.updated` | `subscription.updated` |\n> | Subscription active | (none) | `subscription.active` |\n> | Subscription past due | (none) | `subscription.pastDue` |\n> | Subscription item canceled | `customer.subscription.deleted` | `subscriptionItem.canceled` |\n> | Subscription item past due | `invoice.payment_failed` | `subscriptionItem.pastDue` |\n> | Subscription item updated | (none) | `subscriptionItem.updated` |\n> | Subscription item active | (none) | `subscriptionItem.active` |\n> | Subscription item upcoming renewal | (none) | `subscriptionItem.upcoming` |\n> | Subscription item ended | (none) | `subscriptionItem.ended` |\n> | Subscription item abandoned | (none) | `subscriptionItem.abandoned` |\n> | Subscription item expired | (none) | `subscriptionItem.expired` |\n> | Subscription item incomplete | (none) | `subscriptionItem.incomplete` |\n> | Free trial ending soon | (none) | `subscriptionItem.freeTrialEnding` |\n> | Payment attempt created | (none) | `paymentAttempt.created` |\n> | Payment attempt updated | (none) | `paymentAttempt.updated` |\n>\n> Always use Clerk's event names, never Stripe's, in `evt.type` checks.\n\n> **Payload shape.** Clerk billing webhook payloads are nested. The subscribing entity lives under `evt.data.payer` (fields: `user_id?`, `organization_id?`). The plan info is on each item under `evt.data.items[i].plan.slug`. The subscription id is simply `evt.data.id`. Subscription items do not carry a `subscription_id` field back-reference, so in `subscriptionItem.*` handlers you identify the record by the item id (`evt.data.id`) or look up by payer plus plan.\n\nMinimal handler to anchor the pattern (import from `@clerk\u002Fnextjs\u002Fwebhooks`, verify, branch on Clerk event name):\n\n```typescript\nimport { verifyWebhook } from '@clerk\u002Fnextjs\u002Fwebhooks'\nimport { NextRequest } from 'next\u002Fserver'\nimport { db } from '@\u002Flib\u002Fdb'\n\nexport async function POST(req: NextRequest) {\n\tlet evt\n\ttry {\n\t\tevt = await verifyWebhook(req)\n\t} catch {\n\t\treturn new Response('Verification failed', { status: 400 })\n\t}\n\n\tif (evt.type === 'subscription.created') {\n\t\tconst { id, payer, items, status } = evt.data\n\t\tconst entityId = payer.organization_id ?? payer.user_id\n\t\tconst plan = items[0]?.plan?.slug\n\t\tawait db.subscriptions.upsert({\n\t\t\twhere: { subscriptionId: id },\n\t\t\tcreate: { subscriptionId: id, entityId, plan, status },\n\t\t\tupdate: { entityId, plan, status },\n\t\t})\n\t}\n\n\t\u002F\u002F Add more branches per the event catalog above (subscription.updated,\n\t\u002F\u002F subscriptionItem.canceled, subscriptionItem.pastDue, etc.)\n\n\treturn new Response('OK', { status: 200 })\n}\n```\n\nFor the full template covering all 15 events, the TS type declarations from `@clerk\u002Fbackend`, the `proxy.ts` public-route setup, and the subscription status value table, see `references\u002Fbilling-webhooks.md`.\n\n### 10. Upgrade \u002F Downgrade Flow\n\nLet users manage their subscription from inside the app:\n\n```tsx\nimport { PricingTable } from '@clerk\u002Fnextjs'\nimport { auth } from '@clerk\u002Fnextjs\u002Fserver'\n\nexport default async function BillingPage() {\n\tconst { has } = await auth()\n\tconst isPro = has({ plan: 'pro' })\n\n\treturn (\n\t\t\u003Cdiv>\n\t\t\t\u003Ch1>Billing\u003C\u002Fh1>\n\t\t\t{isPro ? (\n\t\t\t\t\u003Cdiv>\n\t\t\t\t\t\u003Cp>You are on the Pro plan\u003C\u002Fp>\n\t\t\t\t\t\u003CPricingTable \u002F>\n\t\t\t\t\u003C\u002Fdiv>\n\t\t\t) : (\n\t\t\t\t\u003Cdiv>\n\t\t\t\t\t\u003Cp>Upgrade to access premium features\u003C\u002Fp>\n\t\t\t\t\t\u003CPricingTable \u002F>\n\t\t\t\t\u003C\u002Fdiv>\n\t\t\t)}\n\t\t\u003C\u002Fdiv>\n\t)\n}\n```\n\n`\u003CPricingTable \u002F>` renders differently for subscribed users, it shows the current plan and allows upgrades or cancellations, all through Clerk's in-app checkout drawer.\n\n## Plan and Feature Naming\n\nPlan slugs and feature slugs are defined in Clerk Dashboard → Billing. Common conventions:\n\n| Tier | Plan Slug | Example Features |\n|------|-----------|-----------------|\n| Free | (no plan check needed) | basic features |\n| Starter | `starter` | `analytics`, `api_access` |\n| Pro | `pro` | `analytics`, `export`, `team` |\n| Enterprise | `enterprise` | all features + `sso`, `audit_logs` |\n\nUse lowercase slugs matching what you define in the dashboard.\n\n## B2B vs B2C Billing\n\n| Scenario | Who subscribes | Plan check |\n|----------|---------------|------------|\n| B2C SaaS | Individual user | `has({ plan: 'pro' })` on user session |\n| B2B SaaS | Organization | `has({ plan: 'org:team' })` on org session |\n| Seat-limited B2B | Organization | Plan has a seat cap; pricing is per-plan, not per-member, tier your plans for bigger orgs |\n\nFor B2B, ensure the user has an active org session. The `has()` check evaluates the active entity (user or org).\n\n## Checkout Flows\n\nClerk renders its own checkout drawer automatically through `\u003CPricingTable \u002F>` and `\u003CCheckoutButton \u002F>`. Plans and pricing live in Clerk. To trigger checkout from a server action, redirect to a page that renders `\u003CPricingTable \u002F>`:\n\n```typescript\n'use server'\nimport { redirect } from 'next\u002Fnavigation'\n\nexport async function upgradeAction() {\n\tredirect('\u002Fpricing')\n}\n```\n\n## Error Signatures (diagnose fast)\n\nWhen you see any of these errors or symptoms, the fix is almost always a Dashboard toggle, not a code change. Do not start editing components.\n\n| Error \u002F symptom | Root cause | Fix |\n|---|---|---|\n| `Clerk: 🔒 The \u003CPricingTable\u002F> component cannot be rendered when billing is disabled.` (code: `cannot_render_billing_disabled`, dev only) | Billing is not enabled for this instance | Enable Billing at [dashboard.clerk.com → Billing → Settings](https:\u002F\u002Fdashboard.clerk.com\u002Flast-active?path=billing\u002Fsettings), or run `clerk enable billing`. |\n| `\u003CPricingTable \u002F>` renders empty | No plans, OR plan in the wrong tab (User vs Organization), OR Billing not enabled | Create plan in matching tab; pass `for=\"organization\"` for B2B; check Billing Settings |\n| Users can't subscribe to a personal plan on a B2C + B2B app | Membership required mode (default since 2025-08-22) disables personal accounts, signed-in users are forced into `choose-organization` and never land on a personal-subscription state | If you need personal + org subscriptions coexisting: Dashboard → Organizations settings → *Membership optional* |\n| Can't find a Features page | Features are per-plan, not global | Dashboard → Billing → Plans → click plan → Features |\n| `has({ plan: 'pro' })` always returns `false` after a successful checkout | Session token hasn't been refreshed to include the new plan | `await clerk.session?.reload()` or navigate to force a new session |\n| `has({ plan: 'pro' })` returns `false` before any subscribe attempt | Plan slug mismatch (case-sensitive), OR Billing not enabled, OR payment gateway not connected in production | Verify slug in Dashboard → Billing → Plans; confirm Billing → Settings shows enabled + connected gateway |\n| `has({ permission: 'org:x:y' })` returns `false` for a user who has the role | The Feature tied to that permission is not included in the organization's active Plan | Add the Feature to the Plan in Dashboard → Billing → Plans → Features |\n| Webhook 401 \u002F signature verification failed | `CLERK_WEBHOOK_SIGNING_SECRET` mismatch or route protected by middleware | Copy the Signing Secret from Dashboard → Webhooks; add the webhook route to `createRouteMatcher(['\u002Fapi\u002Fwebhooks(.*)'])` |\n\n## Billing Gates Permissions\n\nWhen Billing is enabled, `has({ permission: 'org:posts:edit' })` returns `false` if the Feature associated with that permission is not included in the organization's active Plan, even if the user has the permission assigned via their role. This is by design: billing gates permissions at the feature level. Always ensure the required Feature is attached to the Plan in Dashboard → Billing → Plans → Features.\n\n## See Also\n\n- `clerk-setup` - Initial Clerk install\n- `clerk-orgs` - B2B organizations (required for B2B billing and seat-limit plans)\n- `clerk-webhooks` - Webhook signature verification and routing\n","# Billing\n\n> **STOP, prerequisite.** Billing must be enabled before any `\u003CPricingTable \u002F>`, `\u003CCheckoutButton \u002F>`, `has({ plan })`, or `has({ feature })` usage works. Two paths: (1) [Dashboard → Billing → Settings](https:\u002F\u002Fdashboard.clerk.com\u002Flast-active?path=billing\u002Fsettings), or (2) `clerk enable billing` (see \"Agent-first: Programmatic billing config\" below). Enabling auto-creates default `free_user` \u002F `free_org` plans. Dev instances can use the shared Clerk development gateway (no Stripe account needed); production requires a Stripe account for payment processing only.\n>\n> **Note**: Billing APIs are still experimental. Pin your `@clerk\u002Fnextjs` and `clerk-js` package versions. See `clerk` skill for the supported version table.\n\n## Quick Start\n\n1. **Enable Billing**, via [Dashboard → Billing → Settings](https:\u002F\u002Fdashboard.clerk.com\u002Flast-active?path=billing\u002Fsettings) or `clerk enable billing` (see Agent-first section). Skipping this throws `cannot_render_billing_disabled` in dev and renders empty in prod.\n2. **Create plans in the matching tab**, [Dashboard → Billing → Plans](https:\u002F\u002Fdashboard.clerk.com\u002Flast-active?path=billing\u002Fplans). Two tabs, slugs scoped per tab, not movable after creation:\n   - **User Plans** → `\u003CPricingTable \u002F>` (default `for=\"user\"`)\n   - **Organization Plans** → `\u003CPricingTable for=\"organization\" \u002F>`\n\n   Wrong-tab is the #1 cause of an empty `\u003CPricingTable \u002F>`. Plans live in Clerk; not synced to Stripe.\n3. **Add features inside a plan**, open the plan in Dashboard → Billing → Plans, use its Features section. Features are scoped per plan, not global. The same slug can attach to multiple plans; `has({ feature: 'export' })` matches if the active plan contains that slug.\n4. **Render `\u003CPricingTable \u002F>`** (pass `for=\"organization\"` for B2B).\n5. **Gate access** with `has({ plan })` or `has({ feature })` from `auth()`.\n6. **Handle billing webhooks** for subscription lifecycle.\n\n## Dashboard shortcuts\n\n| Action | URL |\n|---|---|\n| Enable Billing | `https:\u002F\u002Fdashboard.clerk.com\u002Flast-active?path=billing\u002Fsettings` |\n| Create \u002F edit plans | `https:\u002F\u002Fdashboard.clerk.com\u002Flast-active?path=billing\u002Fplans` |\n| Membership mode (B2C + B2B coexistence) | `https:\u002F\u002Fdashboard.clerk.com\u002Flast-active?path=organizations-settings` |\n| Edit features | Plans → click a plan → Features section (no direct URL) |\n\n## Agent-first: Programmatic billing config\n\nThe full billing config (enable toggles, plans, features, plan-feature attachments) is editable via PLAPI without touching the Dashboard. Useful for agents seeding plans, replicating config across instances, or version-controlling billing structure.\n\nPre-req: project linked to the Clerk app (`clerk auth login` + `clerk link`, see `clerk-setup`). Billing is account-only — unlike orgs, it cannot be enabled on an unclaimed app; claim the app first.\n\n### Enable Billing via CLI\n\n```bash\nclerk enable billing                # both targets (default, auto-creates free_user + free_org plans)\nclerk enable billing --for org      # org only\nclerk enable billing --for user     # user only\n```\n\n### Pull current billing config\n\n```bash\nclerk config pull --keys billing > billing.json\n```\n\nThis writes the current billing config (toggles + plans + features) for the linked instance to `billing.json`.\n\n### Edit and apply\n\nEdit `billing.json` to add\u002Fremove plans or features, then preview the diff and apply:\n\n```bash\nclerk config patch --file billing.json --dry-run\nclerk config patch --file billing.json\n```\n\nPass `--instance prod` to target the production instance instead of dev.\n\n### Raw PATCH (full control)\n\nFor one-shot plan\u002Ffeature updates without a config file:\n\n```bash\nclerk api --platform PATCH \u002Fv1\u002Fplatform\u002Fapplications\u002F\u003Capp_id>\u002Finstances\u002F\u003Cins_id>\u002Fconfig \\\n  -d '{\"billing\":{\"plans\":[{\"slug\":\"pro\",\"name\":\"Pro\",\"amount\":2000,\"currency\":\"usd\",\"payer_type\":\"user\",\"is_recurring\":true}],\"features\":[{\"slug\":\"export\",\"name\":\"Export\"}]}}'\n```\n\n### Notes\n\n- This handles **billing config** (toggles + plans + features catalog). **Subscription lifecycle** (users picking a plan, checkout, renewal, cancellation) still flows through `\u003CPricingTable \u002F>` + billing webhooks, see `clerk-webhooks` skill for the lifecycle events.\n- Top-level `features` map manipulation and plan-feature attachments (sync) are fully supported via the PLAPI billing config handler.\n\n## What Do You Need?\n\n| Task | Reference |\n|------|-----------|\n| `\u003CPricingTable \u002F>` props, `\u003CCheckoutButton \u002F>`, `\u003CShow>` billing patterns | references\u002Fbilling-components.md |\n| B2C patterns (individual user subscriptions, `Membership optional` prerequisite) | references\u002Fb2c-patterns.md |\n| B2B patterns (org subscriptions, seat-limit plans, admin-gated billing UI) | references\u002Fb2b-patterns.md |\n| Webhook event catalog, payload shapes, handler templates | references\u002Fbilling-webhooks.md |\n\n## References\n\n| Reference | Description |\n|-----------|-------------|\n| `references\u002Fbilling-components.md` | `\u003CPricingTable \u002F>` and subscription UI |\n| `references\u002Fb2c-patterns.md` | B2C subscription billing patterns |\n| `references\u002Fb2b-patterns.md` | B2B billing with organization subscriptions and seat-limit plans |\n| `references\u002Fbilling-webhooks.md` | Subscription lifecycle event handling |\n\n## Documentation\n\n- [Billing overview](https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fbilling\u002Foverview)\n- [B2B SaaS billing](https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fbilling\u002Ffor-b2b)\n- [B2C SaaS billing](https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fbilling\u002Ffor-b2c)\n- [Billing webhooks](https:\u002F\u002Fclerk.com\u002Fdocs\u002Fguides\u002Fdevelopment\u002Fwebhooks\u002Fbilling)\n\n## Features vs Plans: When to Use Which\n\n**Use `has({ feature: 'slug' })` when gating a specific capability**, export, analytics, API access, audit logs.\n\n**Use `has({ plan: 'slug' })` when gating a tier**, showing the pro dashboard, checking org subscription level, redirecting free users.\n\n| Scenario | Correct check |\n|----------|---------------|\n| Gate the \"Export CSV\" button | `has({ feature: 'export' })` |\n| Gate the \"Analytics\" section | `has({ feature: 'analytics' })` |\n| Gate all of \u002Fdashboard\u002Fpro | `has({ plan: 'pro' })` |\n| Check if org has team subscription | `has({ plan: 'org:team' })` |\n| Gate SSO configuration | `has({ feature: 'sso' })` |\n\nWhen a user says \"gate the export feature\" or \"gate analytics\", always use `has({ feature })`. Only use `has({ plan })` when the gate is the plan tier itself, not a specific capability within it.\n\n## Key Patterns\n\n### 1. Render the Pricing Table\n\nShow available plans to users with a single component:\n\n```tsx\nimport { PricingTable } from '@clerk\u002Fnextjs'\n\nexport default function PricingPage() {\n\treturn (\n\t\t\u003Cmain>\n\t\t\t\u003Ch1>Choose a plan\u003C\u002Fh1>\n\t\t\t\u003CPricingTable \u002F>\n\t\t\u003C\u002Fmain>\n\t)\n}\n```\n\n`\u003CPricingTable \u002F>` automatically renders all plans configured in the Clerk Dashboard. Selecting a plan opens Clerk's in-app checkout drawer. No props needed for basic usage. For B2B, pass `for=\"organization\"` to render org-level plans instead of user plans.\n\n### 2. Check Feature Entitlements (Server-Side)\n\nGate by individual features, this is the preferred approach for specific capabilities:\n\n```typescript\nimport { auth } from '@clerk\u002Fnextjs\u002Fserver'\n\nexport default async function AnalyticsPage() {\n\tconst { has } = await auth()\n\n\tconst canViewAnalytics = has({ feature: 'analytics' })\n\tconst canExport = has({ feature: 'export' })\n\n\treturn (\n\t\t\u003Cdiv>\n\t\t\t{canViewAnalytics && \u003CAnalyticsChart \u002F>}\n\t\t\t{canExport && \u003CExportButton \u002F>}\n\t\t\u003C\u002Fdiv>\n\t)\n}\n```\n\nFeatures are configured in Clerk Dashboard → Billing → Features and assigned to plans. Use `has({ feature })` instead of `has({ plan })` when gating granular capabilities, check the feature, not the plan.\n\n### 3. Check Feature Entitlements (Client-Side)\n\nUse `useAuth()` for client-side feature gating. Combine with server-side checks for full coverage:\n\n```tsx\n'use client'\nimport { useAuth } from '@clerk\u002Fnextjs'\n\nexport function FeatureGatedUI() {\n\tconst { has, isLoaded } = useAuth()\n\tif (!isLoaded) return null\n\n\tconst canExport = has?.({ feature: 'export' })\n\tconst canAnalytics = has?.({ feature: 'analytics' })\n\n\treturn (\n\t\t\u003Cdiv>\n\t\t\t{canAnalytics && \u003CAnalyticsSection \u002F>}\n\t\t\t{canExport ? \u003CExportButton \u002F> : \u003CUpgradeToExport \u002F>}\n\t\t\u003C\u002Fdiv>\n\t)\n}\n```\n\nServer Components use `auth()`, Client Components use `useAuth()`. Both support `has({ feature })` and `has({ plan })`.\n\n### 4. Check Subscription Plan Server-Side\n\nGate access by subscription plan (use this for tier-level gates, not individual features):\n\n```typescript\nimport { auth } from '@clerk\u002Fnextjs\u002Fserver'\nimport { redirect } from 'next\u002Fnavigation'\n\nexport default async function ProDashboard() {\n\tconst { has } = await auth()\n\n\tif (!has({ plan: 'pro' })) {\n\t\tredirect('\u002Fpricing')\n\t}\n\n\treturn \u003CProFeatures \u002F>\n}\n```\n\n### 5. Client-Side Plan Checks\n\nUse `useAuth()` hook for client components:\n\n```tsx\n'use client'\nimport { useAuth } from '@clerk\u002Fnextjs'\n\nexport function UpgradePrompt() {\n\tconst { has } = useAuth()\n\n\tif (has?.({ plan: 'pro' })) {\n\t\treturn null\n\t}\n\n\treturn (\n\t\t\u003Cdiv>\n\t\t\t\u003Cp>Upgrade to Pro to access this feature\u003C\u002Fp>\n\t\t\t\u003Ca href=\"\u002Fpricing\">View plans\u003C\u002Fa>\n\t\t\u003C\u002Fdiv>\n\t)\n}\n```\n\n### 6. B2B Seat-Based Billing with Organizations\n\nOrg plans can carry a **seat limit** (membership cap) that Clerk enforces at invite time. Use the `org:` slug prefix on org-side plan checks (e.g. `has({ plan: 'org:team' })`) to keep gating unambiguous. Render the B2B pricing page with `\u003CPricingTable for=\"organization\" \u002F>`, and use `\u003COrganizationProfile \u002F>` for the org account billing UI.\n\nSee `references\u002Fb2b-patterns.md` for tiered plan naming, seat-limit invariants, admin-only billing, and webhook handlers.\n\n### 7. Display Subscription Status\n\nCheck specific plans with `has({ plan })`, or use `useSubscription()` for full subscription details in client components. Do not read plan information from `sessionClaims` directly, that is not the supported path.\n\nServer component, check for specific plans:\n\n```typescript\nimport { auth } from '@clerk\u002Fnextjs\u002Fserver'\n\nexport default async function AccountPage() {\n\tconst { has } = await auth()\n\n\tconst currentPlan = has({ plan: 'pro' })\n\t\t? 'pro'\n\t\t: has({ plan: 'starter' })\n\t\t\t? 'starter'\n\t\t\t: 'free'\n\n\treturn (\n\t\t\u003Cdiv>\n\t\t\t\u003Ch2>Current Plan\u003C\u002Fh2>\n\t\t\t\u003Cp>You are on the {currentPlan} plan\u003C\u002Fp>\n\t\t\t{currentPlan === 'free' && \u003Ca href=\"\u002Fpricing\">Upgrade\u003C\u002Fa>}\n\t\t\u003C\u002Fdiv>\n\t)\n}\n```\n\nClient component, full subscription details via `useSubscription()`:\n\n```tsx\n'use client'\nimport { useSubscription } from '@clerk\u002Fnextjs\u002Fexperimental'\n\nexport function SubscriptionDetails() {\n\tconst { data: subscription, isLoading } = useSubscription()\n\tif (isLoading) return null\n\tif (!subscription) return \u003Ca href=\"\u002Fpricing\">Choose a plan\u003C\u002Fa>\n\n\treturn (\n\t\t\u003Cdiv>\n\t\t\t\u003Cp>Status: {subscription.status}\u003C\u002Fp>\n\t\t\t{subscription.nextPayment && (\n\t\t\t\t\u003Cp>Next payment: {subscription.nextPayment.date.toLocaleDateString()}\u003C\u002Fp>\n\t\t\t)}\n\t\t\u003C\u002Fdiv>\n\t)\n}\n```\n\n> `useSubscription()` is for display only. For authorization checks (gating content or routes), always use `has({ plan })` or `has({ feature })`.\n\n### 8. Protect API Routes by Plan\n\nGate API routes using `auth()`:\n\n```typescript\nimport { auth } from '@clerk\u002Fnextjs\u002Fserver'\nimport { NextResponse } from 'next\u002Fserver'\n\nexport async function GET() {\n\tconst { has } = await auth()\n\n\tif (!has({ plan: 'pro' })) {\n\t\treturn NextResponse.json({ error: 'Pro plan required' }, { status: 403 })\n\t}\n\n\treturn NextResponse.json({ data: 'premium data' })\n}\n```\n\n### 9. Handle Billing Webhooks\n\n> **Clerk event names differ from Stripe event names.** Clerk billing webhooks use dot-notation and camelCase, not Stripe's underscore format.\n>\n> There is no `subscription.canceled` event. Cancellation fires at the item level as `subscriptionItem.canceled`.\n>\n> | Intent | Stripe event name | Clerk event name |\n> |--------|------------------|-----------------|\n> | Subscription created | `customer.subscription.created` | `subscription.created` |\n> | Subscription updated | `customer.subscription.updated` | `subscription.updated` |\n> | Subscription active | (none) | `subscription.active` |\n> | Subscription past due | (none) | `subscription.pastDue` |\n> | Subscription item canceled | `customer.subscription.deleted` | `subscriptionItem.canceled` |\n> | Subscription item past due | `invoice.payment_failed` | `subscriptionItem.pastDue` |\n> | Subscription item updated | (none) | `subscriptionItem.updated` |\n> | Subscription item active | (none) | `subscriptionItem.active` |\n> | Subscription item upcoming renewal | (none) | `subscriptionItem.upcoming` |\n> | Subscription item ended | (none) | `subscriptionItem.ended` |\n> | Subscription item abandoned | (none) | `subscriptionItem.abandoned` |\n> | Subscription item expired | (none) | `subscriptionItem.expired` |\n> | Subscription item incomplete | (none) | `subscriptionItem.incomplete` |\n> | Free trial ending soon | (none) | `subscriptionItem.freeTrialEnding` |\n> | Payment attempt created | (none) | `paymentAttempt.created` |\n> | Payment attempt updated | (none) | `paymentAttempt.updated` |\n>\n> Always use Clerk's event names, never Stripe's, in `evt.type` checks.\n\n> **Payload shape.** Clerk billing webhook payloads are nested. The subscribing entity lives under `evt.data.payer` (fields: `user_id?`, `organization_id?`). The plan info is on each item under `evt.data.items[i].plan.slug`. The subscription id is simply `evt.data.id`. Subscription items do not carry a `subscription_id` field back-reference, so in `subscriptionItem.*` handlers you identify the record by the item id (`evt.data.id`) or look up by payer plus plan.\n\nMinimal handler to anchor the pattern (import from `@clerk\u002Fnextjs\u002Fwebhooks`, verify, branch on Clerk event name):\n\n```typescript\nimport { verifyWebhook } from '@clerk\u002Fnextjs\u002Fwebhooks'\nimport { NextRequest } from 'next\u002Fserver'\nimport { db } from '@\u002Flib\u002Fdb'\n\nexport async function POST(req: NextRequest) {\n\tlet evt\n\ttry {\n\t\tevt = await verifyWebhook(req)\n\t} catch {\n\t\treturn new Response('Verification failed', { status: 400 })\n\t}\n\n\tif (evt.type === 'subscription.created') {\n\t\tconst { id, payer, items, status } = evt.data\n\t\tconst entityId = payer.organization_id ?? payer.user_id\n\t\tconst plan = items[0]?.plan?.slug\n\t\tawait db.subscriptions.upsert({\n\t\t\twhere: { subscriptionId: id },\n\t\t\tcreate: { subscriptionId: id, entityId, plan, status },\n\t\t\tupdate: { entityId, plan, status },\n\t\t})\n\t}\n\n\t\u002F\u002F Add more branches per the event catalog above (subscription.updated,\n\t\u002F\u002F subscriptionItem.canceled, subscriptionItem.pastDue, etc.)\n\n\treturn new Response('OK', { status: 200 })\n}\n```\n\nFor the full template covering all 15 events, the TS type declarations from `@clerk\u002Fbackend`, the `proxy.ts` public-route setup, and the subscription status value table, see `references\u002Fbilling-webhooks.md`.\n\n### 10. Upgrade \u002F Downgrade Flow\n\nLet users manage their subscription from inside the app:\n\n```tsx\nimport { PricingTable } from '@clerk\u002Fnextjs'\nimport { auth } from '@clerk\u002Fnextjs\u002Fserver'\n\nexport default async function BillingPage() {\n\tconst { has } = await auth()\n\tconst isPro = has({ plan: 'pro' })\n\n\treturn (\n\t\t\u003Cdiv>\n\t\t\t\u003Ch1>Billing\u003C\u002Fh1>\n\t\t\t{isPro ? (\n\t\t\t\t\u003Cdiv>\n\t\t\t\t\t\u003Cp>You are on the Pro plan\u003C\u002Fp>\n\t\t\t\t\t\u003CPricingTable \u002F>\n\t\t\t\t\u003C\u002Fdiv>\n\t\t\t) : (\n\t\t\t\t\u003Cdiv>\n\t\t\t\t\t\u003Cp>Upgrade to access premium features\u003C\u002Fp>\n\t\t\t\t\t\u003CPricingTable \u002F>\n\t\t\t\t\u003C\u002Fdiv>\n\t\t\t)}\n\t\t\u003C\u002Fdiv>\n\t)\n}\n```\n\n`\u003CPricingTable \u002F>` renders differently for subscribed users, it shows the current plan and allows upgrades or cancellations, all through Clerk's in-app checkout drawer.\n\n## Plan and Feature Naming\n\nPlan slugs and feature slugs are defined in Clerk Dashboard → Billing. Common conventions:\n\n| Tier | Plan Slug | Example Features |\n|------|-----------|-----------------|\n| Free | (no plan check needed) | basic features |\n| Starter | `starter` | `analytics`, `api_access` |\n| Pro | `pro` | `analytics`, `export`, `team` |\n| Enterprise | `enterprise` | all features + `sso`, `audit_logs` |\n\nUse lowercase slugs matching what you define in the dashboard.\n\n## B2B vs B2C Billing\n\n| Scenario | Who subscribes | Plan check |\n|----------|---------------|------------|\n| B2C SaaS | Individual user | `has({ plan: 'pro' })` on user session |\n| B2B SaaS | Organization | `has({ plan: 'org:team' })` on org session |\n| Seat-limited B2B | Organization | Plan has a seat cap; pricing is per-plan, not per-member, tier your plans for bigger orgs |\n\nFor B2B, ensure the user has an active org session. The `has()` check evaluates the active entity (user or org).\n\n## Checkout Flows\n\nClerk renders its own checkout drawer automatically through `\u003CPricingTable \u002F>` and `\u003CCheckoutButton \u002F>`. Plans and pricing live in Clerk. To trigger checkout from a server action, redirect to a page that renders `\u003CPricingTable \u002F>`:\n\n```typescript\n'use server'\nimport { redirect } from 'next\u002Fnavigation'\n\nexport async function upgradeAction() {\n\tredirect('\u002Fpricing')\n}\n```\n\n## Error Signatures (diagnose fast)\n\nWhen you see any of these errors or symptoms, the fix is almost always a Dashboard toggle, not a code change. Do not start editing components.\n\n| Error \u002F symptom | Root cause | Fix |\n|---|---|---|\n| `Clerk: 🔒 The \u003CPricingTable\u002F> component cannot be rendered when billing is disabled.` (code: `cannot_render_billing_disabled`, dev only) | Billing is not enabled for this instance | Enable Billing at [dashboard.clerk.com → Billing → Settings](https:\u002F\u002Fdashboard.clerk.com\u002Flast-active?path=billing\u002Fsettings), or run `clerk enable billing`. |\n| `\u003CPricingTable \u002F>` renders empty | No plans, OR plan in the wrong tab (User vs Organization), OR Billing not enabled | Create plan in matching tab; pass `for=\"organization\"` for B2B; check Billing Settings |\n| Users can't subscribe to a personal plan on a B2C + B2B app | Membership required mode (default since 2025-08-22) disables personal accounts, signed-in users are forced into `choose-organization` and never land on a personal-subscription state | If you need personal + org subscriptions coexisting: Dashboard → Organizations settings → *Membership optional* |\n| Can't find a Features page | Features are per-plan, not global | Dashboard → Billing → Plans → click plan → Features |\n| `has({ plan: 'pro' })` always returns `false` after a successful checkout | Session token hasn't been refreshed to include the new plan | `await clerk.session?.reload()` or navigate to force a new session |\n| `has({ plan: 'pro' })` returns `false` before any subscribe attempt | Plan slug mismatch (case-sensitive), OR Billing not enabled, OR payment gateway not connected in production | Verify slug in Dashboard → Billing → Plans; confirm Billing → Settings shows enabled + connected gateway |\n| `has({ permission: 'org:x:y' })` returns `false` for a user who has the role | The Feature tied to that permission is not included in the organization's active Plan | Add the Feature to the Plan in Dashboard → Billing → Plans → Features |\n| Webhook 401 \u002F signature verification failed | `CLERK_WEBHOOK_SIGNING_SECRET` mismatch or route protected by middleware | Copy the Signing Secret from Dashboard → Webhooks; add the webhook route to `createRouteMatcher(['\u002Fapi\u002Fwebhooks(.*)'])` |\n\n## Billing Gates Permissions\n\nWhen Billing is enabled, `has({ permission: 'org:posts:edit' })` returns `false` if the Feature associated with that permission is not included in the organization's active Plan, even if the user has the permission assigned via their role. This is by design: billing gates permissions at the feature level. Always ensure the required Feature is attached to the Plan in Dashboard → Billing → Plans → Features.\n\n## See Also\n\n- `clerk-setup` - Initial Clerk install\n- `clerk-orgs` - B2B organizations (required for B2B billing and seat-limit plans)\n- `clerk-webhooks` - Webhook signature verification and routing\n",{"license":15,"metadata":24,"description":7},{"author":25,"version":26},"clerk","1.1.0","main","7540bbccf0c1ded6156a467b02c95b61ad62413f",".agents\u002Fskills\u002Fclerk-billing","https:\u002F\u002Fgithub.com\u002FNeelakshSaxena\u002FVayu","https:\u002F\u002Fgithub.com\u002FNeelakshSaxena","Currently exploring the intersection of tech","2026-09-11 03:02:31",{"source":8,"skillName":5,"commands":35,"prompt":45,"zipAvailable":46},[36,39,42],{"tool":37,"command":38},"npx","npx skills add NeelakshSaxena\u002FVayu --skill clerk-billing",{"tool":40,"command":41},"bunx","bunx skills add NeelakshSaxena\u002FVayu --skill clerk-billing",{"tool":43,"command":44},"pnpm","pnpm dlx skills add NeelakshSaxena\u002FVayu --skill clerk-billing","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FNeelakshSaxena\u002FVayu\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fclerk-billing\u002FSKILL.md",true,[48,54,58,62,66],{"path":49,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":52,"sourceHtmlUrl":53},"evals\u002Fevals.json","REFERENCE","参考文档",15403,"https:\u002F\u002Fgithub.com\u002FNeelakshSaxena\u002FVayu\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fclerk-billing\u002Fevals\u002Fevals.json",{"path":55,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":56,"sourceHtmlUrl":57},"references\u002Fb2b-patterns.md",5173,"https:\u002F\u002Fgithub.com\u002FNeelakshSaxena\u002FVayu\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fclerk-billing\u002Freferences\u002Fb2b-patterns.md",{"path":59,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":60,"sourceHtmlUrl":61},"references\u002Fb2c-patterns.md",4169,"https:\u002F\u002Fgithub.com\u002FNeelakshSaxena\u002FVayu\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fclerk-billing\u002Freferences\u002Fb2c-patterns.md",{"path":63,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":64,"sourceHtmlUrl":65},"references\u002Fbilling-components.md",4871,"https:\u002F\u002Fgithub.com\u002FNeelakshSaxena\u002FVayu\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fclerk-billing\u002Freferences\u002Fbilling-components.md",{"path":67,"resourceType":50,"resourceTypeDesc":51,"sizeBytes":68,"sourceHtmlUrl":69},"references\u002Fbilling-webhooks.md",7799,"https:\u002F\u002Fgithub.com\u002FNeelakshSaxena\u002FVayu\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fclerk-billing\u002Freferences\u002Fbilling-webhooks.md",[71,79,86,93,100,107],{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":75,"licenseFileUrl":6,"sourceHtmlUrl":76,"categories":77,"keywords":78,"publishedAt":19},"01M7ACCCVNCFKMA9X6D15X6G98","runpodctl","Runpod CLI for managing GPU\u002FCPU workloads from the terminal — pods, serverless endpoints, templates, network volumes, Hub deploys, models, SSH, and file transfer (send\u002Freceive). Use for terminal\u002FCI\u002Fscripting, Hub browse\u002Fdeploy, SSH setup, `doctor`, or when the Runpod MCP tools are not connected. For structured tool calls in an MCP-enabled session, prefer runpod-mcp.","Apache-2.0","https:\u002F\u002Fgithub.com\u002FNeelakshSaxena\u002FVayu\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Frunpodctl\u002FSKILL.md",[],[],{"skillNo":80,"name":81,"nameZh":6,"description":82,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":75,"licenseFileUrl":6,"sourceHtmlUrl":83,"categories":84,"keywords":85,"publishedAt":19},"01M7ACC63SRHEA5KMCHSMZK2TC","runpod","Start here for any Runpod task — running GPU\u002FCPU pods, deploying serverless endpoints, templates, network volumes, building images, or understanding how Runpod works. Routes to the right skill (runpod-mcp, runpodctl, flash, companion-clis, runpod-usage, runpod-templates, runpod-migrate) and indexes two dozen live-verified end-to-end examples (golden paths) — use it when the lane is unclear, and for any multi-step or provisioning task even when it is not.","https:\u002F\u002Fgithub.com\u002FNeelakshSaxena\u002FVayu\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Frunpod\u002FSKILL.md",[],[],{"skillNo":87,"name":88,"nameZh":6,"description":89,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":75,"licenseFileUrl":6,"sourceHtmlUrl":90,"categories":91,"keywords":92,"publishedAt":19},"01M7ACC0Q1C89N9BZBV91CTQTF","runpod-usage","How Runpod works and how to work it — pods vs serverless, GPU\u002FVRAM selection, storage, building a container, networking, plus the agentic pod development loop (provision → ssh-exec → set up → poll readiness) and on-pod install hygiene (uv\u002Fapt). Use to answer \"how does X work\", \"which GPU\", \"how do I build a container\", or \"how do I stand up a workload on a pod\". Guidance, not a tool — execute with runpodctl, runpod-mcp, or flash.","https:\u002F\u002Fgithub.com\u002FNeelakshSaxena\u002FVayu\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Frunpod-usage\u002FSKILL.md",[],[],{"skillNo":94,"name":95,"nameZh":6,"description":96,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":75,"licenseFileUrl":6,"sourceHtmlUrl":97,"categories":98,"keywords":99,"publishedAt":19},"01M7ACBRPE345GF5GM5B8P8RRC","runpod-templates","Runpod's official prebuilt pod templates (ComfyUI, PyTorch, and others): what each image ships, which ports and paths it uses, how to pick one, how to pin a version, and what is missing on first boot. Use when a task says \"run \u003CX> on a pod\" and an official template already covers it, instead of building an image — and when a user needs help with or wants to fix something about a Runpod template they are already running (won't boot, can't reach the UI, missing models, wrong CUDA line, broken ComfyUI workflow metadata on imported workflows): start here and route onward. Deploy with runpodctl or runpod-mcp; end-to-end walkthroughs live in the runpod router's golden paths.","https:\u002F\u002Fgithub.com\u002FNeelakshSaxena\u002FVayu\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Frunpod-templates\u002FSKILL.md",[],[],{"skillNo":101,"name":102,"nameZh":6,"description":103,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":75,"licenseFileUrl":6,"sourceHtmlUrl":104,"categories":105,"keywords":106,"publishedAt":19},"01M7ACBJATHKVX1TWES2F44GY8","runpod-migrate","Migrate a codebase from the Runpod GraphQL API or REST v1 to REST v2 — inventory which parts use which API version, rewrite the call sites, flag breaking changes, and verify. Use when someone asks to move to v2, asks what v2 would change, or asks which Runpod API their code is on. For managing infrastructure rather than migrating code, use runpod-mcp or runpodctl.","https:\u002F\u002Fgithub.com\u002FNeelakshSaxena\u002FVayu\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Frunpod-migrate\u002FSKILL.md",[],[],{"skillNo":108,"name":109,"nameZh":6,"description":110,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":75,"licenseFileUrl":6,"sourceHtmlUrl":111,"categories":112,"keywords":113,"publishedAt":19},"01M7ACBC7GHVH6T9YEAPCG2AP8","runpod-mcp","Manage Runpod infrastructure — pods, serverless endpoints, jobs, templates, network volumes, container-registry auth, GPU\u002FCPU catalog, and billing — via the Runpod MCP server's structured tool calls. Use when the Runpod MCP tools (create-pod, list-endpoints, …) are connected in this session, or to connect them (hosted OAuth or local npx). Prefer this over runpodctl for plain infra CRUD when MCP is available; use runpodctl for the terminal, file transfer, or SSH setup.","https:\u002F\u002Fgithub.com\u002FNeelakshSaxena\u002FVayu\u002Fblob\u002Fmain\u002F.claude\u002Fskills\u002Frunpod-mcp\u002FSKILL.md",[],[]]