docs(repo): Fixing billing broken links for Typedoc output

[SarahSoutoul]

Description

Fixes broken and incomplete TypeDoc links and generated documentation for several billing types and checkout methods. The broken links were spotted in this TypeDoc-generated PR, which will ultimately be closed once this PR generates a new TypeDoc PR.

This PR:

• Adds canonical Clerk Docs link replacements for:
  • BillingAppliedDiscount
  • BillingCredits
  • BillingDiscountRedemption
  • BillingDiscounts
  • BillingPaymentTotals
  • BillingPayerCredit
  • BillingPeriodTotals
  • BillingProrationCreditDetail
  • BillingProrationDiscount
  • BillingSubscriptionItemNextPayment
  • BillingSubscriptionNextPayment
  • ConfirmCheckoutParams
  • UpdateCheckoutParams
• Corrects the checkout parameter links:
  • ConfirmCheckoutParams now links to #confirm-parameters.
  • UpdateCheckoutParams now links to #update-parameters.
• Replaces the relative #confirm and #update links with canonical BillingCheckoutResource URLs so they work when TypeDoc is embedded on other pages, such as useCheckout().
• Refactors UpdateCheckoutParams into a directly documented object type while preserving its existing id, orgId, and promoCode properties. This allows TypeDoc to generate a complete standalone property table.
• Removes the generated Properties heading from update-checkout-params.mdx so the fragment embeds cleanly beneath the Update parameters heading.
• Adds complete JSDoc comments for:
  • BillingCredits
  • BillingPayerCredit
  • BillingProrationCreditDetail
  • BillingAppliedDiscount
  • BillingDiscountRedemption
• Documents the BillingCredits properties on BillingCheckoutTotals and BillingSubscriptionItemResource, which were previously omitted from the generated output.
• Marks ProtectAssertion and ProtectAssertionResolver as inline types so TypeDoc does not generate broken standalone links.

A fresh TypeDoc generation now produces standalone fragments with complete property tables for all five previously missing billing types:

• billing-credits.mdx
• billing-payer-credit.mdx
• billing-proration-credit-detail.mdx
• billing-applied-discount.mdx
• billing-discount-redemption.mdx

In addition, update-checkout-params.mdx now renders a complete parameter table without a redundant Properties heading.

clerk/clerk#3135 fixed the billing links whose TypeDoc fragments were already synced with Clerk Docs.

The five newly generated fragments above were intentionally not included in that Clerk PR. Once this JavaScript PR is released and the updated TypeDoc output is synced into Clerk Docs, I will merge clerk/clerk#3153 into the TypeDoc-generated PR to complete the remaining documentation changes.

To verify the changes, run:

pnpm test:typedoc

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:

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Aug 13, 2026 3:30pm
swingset	Ready	Preview	Aug 13, 2026 3:30pm

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@9393

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@9393

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@9393

@clerk/expo

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

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@9393

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 3b79795

[changeset-bot]

🦋 Changeset detected

Latest commit: 3b79795

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

This PR includes changesets to release 23 packages

Name	Type
@clerk/shared	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/electron	Patch
@clerk/expo-passkeys	Patch
@clerk/expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/headless	Patch
@clerk/hono	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/react	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/ui	Patch
@clerk/vue	Patch
@clerk/swingset	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

[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 Plus

Run ID: 275f7eab-e5c6-4cd7-a891-768d390a042b

📥 Commits

Reviewing files that changed from the base of the PR and between 915d390 and 3b79795.

📒 Files selected for processing (4)

• .changeset/fix-billing-typedoc-pages.md
• .typedoc/custom-plugin.mjs
• packages/shared/src/types/billing.ts
• packages/shared/src/types/protectConfig.ts

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• clerk/clerk_go (manual)
• clerk/dashboard (manual)
• clerk/accounts (manual)
• clerk/backoffice (manual)
• clerk/clerk (manual) → reviewed against open PR #3153 ss/more-fixes-typedoc-billing instead of the default branch
• clerk/clerk-docs (manual)
• clerk/cloudflare-workers (manual)
• clerk/clerk-ios (auto-detected)
• clerk/cli (auto-detected)
• clerk/clerk-android (auto-detected)

---

📝 Walkthrough

Walkthrough

The PR adds Billing documentation for credits, proration, discounts, and checkout fields. It restructures UpdateCheckoutParams without changing its effective fields. It updates checkout and Billing TypeDoc links and heading handling. It adds @inline annotations to Protect assertion types and creates a patch changeset for @clerk/shared.

Estimated code review effort: 2 (Simple) | ~10 minutes

Mergeability Score: ⚪ Minimal · up to 3b797

This localized documentation and TypeDoc link update is merge-ready after normal checks and review; no actionable merge-blocking risk remains.

Possibly related PRs

• clerk/javascript#9316: Both PRs modify Billing discount types.
• clerk/javascript#9340: Both PRs modify Billing TypeDoc link replacements.
• clerk/javascript#9313: Both PRs modify Protect assertion type documentation.

Suggested reviewers: alexisintech

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: fixing broken billing links in TypeDoc output.
Description check	✅ Passed	The description directly explains the TypeDoc link fixes, JSDoc updates, generated fragments, and verification steps.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

---

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

[github-actions]

API Changes Report

Generated by Break Check on 2026-08-13T15:35:13.878Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	1
🔴 Breaking changes	0
🟡 Non-breaking changes	1
🟢 Additions	0

🤖 This report was reviewed by claude-sonnet-4-6.

---

@clerk/shared

Current version: 4.28.1
Recommended bump: MINOR → 4.29.0

Subpath ./types

🟡 Non-breaking Changes (1)

Modified: UpdateCheckoutParams

- type UpdateCheckoutParams = WithOptionalOrgType<{
+ type UpdateCheckoutParams = {
    id: string;
+   orgId?: string;
    promoCode: string;
- }>;
+ };

Static analyzer: Breaking change in type alias UpdateCheckoutParams: Type changed: import("@clerk/shared").WithOptionalOrgType<{id:string;promoCode:string;}> → {id:string;orgId?:string;promoCode:string;}

🤖 AI review (reclassified as non-breaking) (97%): The resolved shape of WithOptionalOrgType<{id:string;promoCode:string;}> is {id:string;promoCode:string;orgId?:string;}, which is structurally identical to the inlined {id:string;orgId?:string;promoCode:string;} — only the representation changed, not the assignable set.

---

Report generated by Break Check

_{Last ran on 3b79795.}