feat(ui): show management button for plans without base fee

[mauricioabreu]

Today, the Manage Subscription button in / , and the Cancel / Re-subscribe actions inside , are gated by !plan.hasBaseFee. That predicate was originally shorthand for "this is the free fallback plan, there's nothing the user can do with it". with seat-based billing, however, a plan can have no base fee and still be a real paid subscription (the cost comes entirely from the seat unit prices), so the UI was hiding actions users need

Description

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

[changeset-bot]

🦋 Changeset detected

Latest commit: 81ea3f0

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@clerk/ui	Patch
@clerk/chrome-extension	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	May 21, 2026 7:31pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: 1e42aff4-9fb3-4fc2-9130-6926e47a6230

📥 Commits

Reviewing files that changed from the base of the PR and between 7654711 and 81ea3f0.

📒 Files selected for processing (1)

• .changeset/billing-manage-subscription-seat-based.md

✅ Files skipped from review due to trivial changes (1)

• .changeset/billing-manage-subscription-seat-based.md

---

📝 Walkthrough

Walkthrough

A new utility, isManageableSubscriptionItem(subscriptionItem), is added and exported from packages/ui/src/utils/billingSubscription.ts; it defines manageability as !subscriptionItem.plan.isDefault. The SubscriptionDetails and SubscriptionsList components now use this helper to decide whether management actions (manage/switch/cancel/re-subscribe) and the manage-subscription button are shown, replacing prior local checks that relied on plan base-fee and free-plan heuristics. A changeset documenting the UI behavior update was added.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately captures the main change: showing the management button for plans without base fee by introducing seat-based billing support.
Description check	✅ Passed	The description clearly explains the problem (free plans previously detected via !plan.hasBaseFee logic) and the solution (refactoring to distinguish paid seat-based plans from free fallback plans).
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/ui/src/utils/billingSubscription.ts`:
- Around line 15-16: Add regression tests for the new predicate
isManageableSubscriptionItem(BillingSubscriptionItemResource) covering at least:
(1) a default-plan item where plan.isDefault === true and the predicate returns
false, and (2) paid seat-based and paid no-base-fee items where plan.isDefault
=== false and the predicate returns true. Also add integration-level assertions
that the UI paths which rely on this helper (the action visibility
logic/components that call isManageableSubscriptionItem) show or hide the
management actions appropriately. Ensure tests exercise the helper directly and
via the consuming UI visibility logic so future changes to
isManageableSubscriptionItem are caught.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: 22136a0a-d6e8-4522-9cfc-d9ccf9a95a08

📥 Commits

Reviewing files that changed from the base of the PR and between abaa339 and d02bd0b.

📒 Files selected for processing (4)

• .changeset/billing-manage-subscription-seat-based.md
• packages/ui/src/components/SubscriptionDetails/index.tsx
• packages/ui/src/components/Subscriptions/SubscriptionsList.tsx
• packages/ui/src/utils/billingSubscription.ts

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@8375

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@8375

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@8375

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@8375

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@8375

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@8375

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@8375

@clerk/express

npm i https://pkg.pr.new/@clerk/express@8375

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@8375

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@8375

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@8375

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@8375

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@8375

@clerk/react

npm i https://pkg.pr.new/@clerk/react@8375

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@8375

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@8375

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@8375

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@8375

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@8375

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@8375

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@8375

commit: 81ea3f0