Skip to content

feat: add doc for seat-based billing plans - #3414

Merged
paddycarver merged 28 commits into
mainfrom
lamone/bill-1722-docs-write-documentation-for-per-seat-pricing
Jun 10, 2026
Merged

paddycarver merged 28 commits into
mainfrom
lamone/bill-1722-docs-write-documentation-for-per-seat-pricing

Conversation

@l-armstrong

@l-armstrong l-armstrong commented Jun 3, 2026 •

Copy link
Copy Markdown
Contributor

🔎 Previews:

What does this solve? What changed?

  • The documentation is needed to give our users more information about seat-based billing for Clerk Billing.

Deadline

  • Ideally shipped by the week of June 8th.

@vercel

vercel Bot commented Jun 3, 2026 •

Copy link
Copy Markdown

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

Project Deployment Actions Updated (UTC)
clerk-docs Error Error Jun 11, 2026 3:26pm

Request Review

@ssibley-clerk

Copy link
Copy Markdown

When testing and clicking the "new organization plan" hyperlink, the org plan is in a disabled state. Are there certain pre-reqs to create a plan, and if so, do we expect customers on this doc to have already met those?

@l-armstrong

Copy link
Copy Markdown
Contributor Author

When testing and clicking the "new organization plan" hyperlink, the org plan is in a disabled state. Are there certain pre-reqs to create a plan, and if so, do we expect customers on this doc to have already met those?

@ssibley-clerk I'm assuming by "org plans is in a disabled state" you mean that the "Enable organization billing" toggle is off. We currently allows users to create plans while this toggle is off. We surface in the UI a warning stating that the toggle is off if plans were created for orgs.

Screenshot 2026-06-05 at 7 35 53 PM

@l-armstrong

Copy link
Copy Markdown
Contributor Author

Is it worth merging this page with the "Plans with seat limits" page?

I personally don't think so. @paddycarver

@SarahSoutoul SarahSoutoul self-assigned this Jun 10, 2026
Comment thread docs/guides/billing/seat-limit-plans.mdx
Comment on lines +56 to +60
> [!IMPORTANT]
>
> - Organizations subscribed to Plans that are not seat-based will have their membership limit set to the [default membership limit](/docs/guides/organizations/configure#membership-limits). This can be overridden on a per-Organization basis.
> - If an Organization's seats are forcibly reduced (for example, when its Subscription ends), the Organization will keep its currently provisioned seats but cannot invite new members until it is under the new seat limit.
> - When an Organization is on a seat-based Plan, you cannot manually set the Organization's seat limit.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This callout feels out of place to me because it talks more about seat-based limits than per-seat pricing. We could move it down under Managing seat limits for e.g., and even make it a paragraph rather than a callout. But open to suggestions @l-armstrong @paddycarver

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The complicated thing to navigate here is there are two different types of seat limit: there's the maximum number of seats that can be purchased under a plan, period, and then there's the number of members the Organization can have without purchasing more seats.

When there was just plan limits, these two numbers were the same. With per-seat pricing, these two numbers are usually different.

These three bullets apply to the number of seats that an Organization has / the number of members the Organization can have without purchasing more seats, a concept that applies to both plan limits and to per-seat pricing.

I'm not sure I have an opinion on where to put it, but I wanted to info dump quick on some of the complexity when we talk about "seat limits".

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about this?

Screenshot 2026-06-10 at 1 03 34 pm

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just moved it to "managing seat limits", and I think we're on board with that -- do you like that, or is putting it at the top better?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me!

@paddycarver
paddycarver merged commit 358c7d4 into main Jun 10, 2026
8 checks passed
@paddycarver
paddycarver deleted the lamone/bill-1722-docs-write-documentation-for-per-seat-pricing branch June 10, 2026 19:40

This branch was successfully deployed

1 active deployment
Preview — 1208c98f Deployed Jun 10, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

7 participants