Update Backend Commerce --> Billing; fix BAPI links

[alexisintech]

🔎 Previews:

What does this solve? What changed?

BAPI link fixes

Scalar requires that HTTP methods (GET, POST, PATCH, DELETE) be capitalized in URLs, otherwise the link is wrong. This PR audits every BAPI reference link in the docs and fixes the lowercase ones, plus catches a few links left stale by the commerce → billing rename.

This PR also:

• Renames the backend type docs from commerce-* to billing-* to match the source (BillingApi, BillingPlan, BillingSubscription, BillingSubscriptionItem):
  • types/commerce-plan.mdx → types/billing-plan.mdx
  • types/commerce-subscription.mdx → types/billing-subscription.mdx
  • types/commerce-subscription-item.mdx → types/billing-subscription-item.mdx
• Updates manifest.json and adds redirects.
• Updated reference material to match source code.
• Adds extendSubscriptionItemFreeTrial(), which exists in BillingApi.ts but was previously undocumented.

Related changes were made in clerk/javascript to update broken BAPI links there as well: clerk/javascript#8655

TODO: test every single URL. Ensure the version is getting injected and that the URL is working.

• user
• billing
• organization
• allowlist
• domains
• sessions
• client
• invitations
• redirect urls
• email addresses
• phone numbers
• saml connections
• sign in tokens
• agent tasks
• testing tokens
• waitlist entries
• machines
• m2m tokens
• api keys
• oauth applications

Deadline

High priority - broken links in prod docs, missing reference info

Other resources

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-docs	Ready	Preview	May 27, 2026 8:35pm

[manovotny]

Pushed some additional BAPI link fixes in cc3d716:

• update-user.mdx line 104 still had tag/users/post/users even after line 226 was uppercased in this PR — fixed.
• commerce-subscription.mdx line 8 wasn't in the diff and still had tag/billing/get/... — fixed.
• The two checkout-*-payment-method.mdx URLs had a dangling #tag/commerce/get/commerce/plans fragment. Dropped it (it was Redocly-era cruft) and also retargeted the URL — see the next bullet.
• migrating/overview.mdx line 28 changed from a Redocly anchor to tag/users/POST/users.body.password_hasher. The body.<field> form is the right Scalar shape for inline scalar fields, but password_hasher is $ref'd to a PasswordHasher schema, and Scalar doesn't emit per-field anchors for $ref'd schemas. Confirmed live: the URL landed at scrollY=0. Stripped the suffix back to tag/users/POST/users so the link at least lands on Create User.

While verifying these against the latest BAPI spec (clerk_go 2025-11-10), a few things came up worth knowing about:

The commerce tag was renamed to Billing in 2025-11-10. Four URLs in the PR (get-plan-list.mdx, cancel-subscription-item.mdx, and the two checkout-*-payment-method.mdx files) still pointed at tag/commerce/... operations, which no longer exist in the rendered Scalar ref. I retargeted those to tag/billing/.... The mechanical method-case fix wouldn't catch this kind of drift, so it might be worth a broader spot-check on the rest of the touched URLs against operations renamed across API versions.

Two SDK reference pages have prose drift outside the URL. get-plan-list.mdx and cancel-subscription-item.mdx still describe their wrapped endpoint as GET /commerce/plans / DELETE /commerce/subscription_items/{id} even though the BAPI spec only exposes /billing/... now. Might be out of scope for this PR — flagging and we can decide to handle it now or as a follow-up.

Let me know if any of these are incorrect.

[alexisintech]

Pushed some additional BAPI link fixes in cc3d716:

• update-user.mdx line 104 still had tag/users/post/users even after line 226 was uppercased in this PR — fixed.
• commerce-subscription.mdx line 8 wasn't in the diff and still had tag/billing/get/... — fixed.
• The two checkout-*-payment-method.mdx URLs had a dangling #tag/commerce/get/commerce/plans fragment. Dropped it (it was Redocly-era cruft) and also retargeted the URL — see the next bullet.
• migrating/overview.mdx line 28 changed from a Redocly anchor to tag/users/POST/users.body.password_hasher. The body.<field> form is the right Scalar shape for inline scalar fields, but password_hasher is $ref'd to a PasswordHasher schema, and Scalar doesn't emit per-field anchors for $ref'd schemas. Confirmed live: the URL landed at scrollY=0. Stripped the suffix back to tag/users/POST/users so the link at least lands on Create User.

While verifying these against the latest BAPI spec (clerk_go 2025-11-10), a few things came up worth knowing about:

The commerce tag was renamed to Billing in 2025-11-10. Four URLs in the PR (get-plan-list.mdx, cancel-subscription-item.mdx, and the two checkout-*-payment-method.mdx files) still pointed at tag/commerce/... operations, which no longer exist in the rendered Scalar ref. I retargeted those to tag/billing/.... The mechanical method-case fix wouldn't catch this kind of drift, so it might be worth a broader spot-check on the rest of the touched URLs against operations renamed across API versions.

Two SDK reference pages have prose drift outside the URL. get-plan-list.mdx and cancel-subscription-item.mdx still describe their wrapped endpoint as GET /commerce/plans / DELETE /commerce/subscription_items/{id} even though the BAPI spec only exposes /billing/... now. Might be out of scope for this PR — flagging and we can decide to handle it now or as a follow-up.

Let me know if any of these are incorrect.

I've updated anything that still referenced commerce, including the endpoints!

[SarahSoutoul]

@alexisintech have pushed a small commit to fix a malformed link + left a comment.

Other stuff I noticed:

1. Do we want to change the API error names below as well or are these still standing?

   

2. We prob need a JS sibling PR to update the Typedoc outputs as well?

   

Gonna test the links now!

[SarahSoutoul]

@manovotny @alexisintech made a list of all of the links that needed testing: https://www.notion.so/clerkdev/Testing-links-BAPI-36c2b9ab44fe80dfac27de87b42d3b91?source=copy_link. If it helps!

[alexisintech]

@alexisintech have pushed a small commit to fix a malformed link + left a comment.

Other stuff I noticed:

1. Do we want to change the API error names below as well or are these still standing?
   
   
2. We prob need a JS sibling PR to update the Typedoc outputs as well?
   

Gonna test the links now!

yeah I noticed that as well when I did the search all for commerce - but the api errors docs are generated from our go specs. it's a good point that we can initiate the conversation and ask team sdk if they intend on changing them 👀

and to the typedoc point - yes! I missed this, we should totally do that. I'll open a typedoc pr!

[alexisintech]

typedoc PR created: clerk/javascript#8655

[alexisintech]

asked team SDK about the commerce errors: https://clerkinc.slack.com/archives/C0AJBKMHB51/p1779829689567829

[alexisintech]

typedoc has been updated for BAPI links! [ci] Update Typedoc (0796911) - Core 3

I believe this should be good to merge :) @SarahSoutoul