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 14, 2026 6:56pm
swingset	Ready	Preview	Aug 14, 2026 6:56pm

[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: 61835eb

[changeset-bot]

🦋 Changeset detected

Latest commit: 61835eb

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: a721446a-a6bc-477e-9eac-88a481dc97c7

📥 Commits

Reviewing files that changed from the base of the PR and between 3b79795 and 763376e.

📒 Files selected for processing (3)

• .changeset/fix-billing-typedoc-pages.md
• .typedoc/__tests__/relative-link-replacements.test.ts
• packages/shared/src/types/billing.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 #3134 typedoc-167204b 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)

🚧 Files skipped from review as they are similar to previous changes (2)

• .changeset/fix-billing-typedoc-pages.md
• packages/shared/src/types/billing.ts

---

📝 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 tests for relative link replacements and @inline annotations to Protect assertion types. It creates a patch changeset for @clerk/shared.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 76337

This change updates generated documentation links and TypeDoc annotations without any identified actionable merge-blocking risk remaining.

Suggested reviewers: manovotny

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description clearly explains the TypeDoc link fixes, billing documentation updates, refactoring, tests, and verification steps.
Title check	✅ Passed	The title clearly identifies the main change: fixing broken billing links in TypeDoc output.
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-14T18:56:15.790Z

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.29.0
Recommended bump: MINOR → 4.30.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 structurally identical to {id:string;orgId?:string;promoCode:string;} — the alias merely inlines the intersection, producing the same set of required and optional properties. No consumer code is affected.

---

Report generated by Break Check

_{Last ran on 61835eb.}

[manovotny]

Pushed some changes directly in 763376e.

• Added JSDoc for BillingAppliedDiscount.durationInCycles — it was the only property in that interface without a comment, so excludeNotDocumented was dropping it from the generated billing-applied-discount.mdx, leaving the table incomplete.
• Reworded amountOff on BillingAppliedDiscount and BillingDiscountRedemption to describe it as the configured fixed amount, distinct from amount (what's actually applied to the transaction) — matches the Commerce schema's configured-vs-applied split.
• Switched the three checkout [Learn more.] links to absolute https://clerk.com/docs/... URLs so they resolve in IntelliSense; the TypeDoc replaceText rule strips them back to relative /docs/... for the docs site, matching what the rest of the package does.
• Added .typedoc/__tests__/relative-link-replacements.test.ts covering the billing link replacements, anchor preservation, and the .mdx-boundary substring safety, so a wrong route/anchor can't pass CI silently.
• Tweaked the changeset ("TypeDoc" spelling + mention the added type descriptions).