New API version release

[brunol95]

🔎 Previews:

• https://clerk.com/docs/pr/bruno-user-5311-latest-api-version/guides/users/extending
• https://clerk.com/docs/pr/bruno-user-5311-latest-api-version/guides/development/upgrading/versioning#2026-05-12
• https://clerk.com/docs/pr/bruno-user-5311-latest-api-version/guides/development/upgrading/upgrade-guides/2026-05-12
• https://clerk.com/docs/pr/bruno-user-5311-latest-api-version/js-frontend/reference/objects/user#update
• https://clerk.com/docs/pr/bruno-user-5311-latest-api-version/reference/backend/user/update-user
• https://clerk.com/docs/pr/bruno-user-5311-latest-api-version/guides/development/add-onboarding-flow#update-the-users-public-metadata-in-your-backend
• https://clerk.com/docs/pr/bruno-user-5311-latest-api-version/reference/backend/organization/update-organization
• https://clerk.com/docs/pr/bruno-user-5311-latest-api-version/reference/backend/organization/replace-organization-metadata
• https://clerk.com/docs/pr/bruno-user-5311-latest-api-version/guides/organizations/metadata

What does this solve? What changed?

In the next API version, metadata updates through the user update method are disallowed. This PR documents the API version page along with sdk changes to support the new version.

Todos

• Update/Finalize API version date
• Merge chore(backend, clerk-js): Deprecate metadata updates in user update methods javascript#8587
• Merge chore(backend): Deprecate metadata updates in organization update method javascript#8787
• Merge deprecate the metadata fields in user update clerk-android#650 will be addressed in follow up PR
• Merge deprecate metadata field in user update clerk-ios#415
• Update SDK version TBDs (see reminder comment)

Deadline

• 05/26

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-docs	Ready	Preview	Jun 13, 2026 2:47am

[manovotny]

Pushed some review fixes directly in 3414da8.

• Fixed the del/ins line ranges in the metadata examples so the diff highlighting is correct: the backend example in the 2026-05-12 guide now highlights replaceUserMetadata()'s closing line, and the frontend user.update() examples (in both the 2026-05-12 guide and the Core 3 accordion) now account for the 6-line block instead of treating it as 5.
• Switched the native iOS/Android > Note: blockquotes to > [!NOTE] callouts to match the other native-mobile pages.
• Renamed the updateUserMetadata() params type from UpdateUserMetadataParams to UserMetadataParams so it matches @clerk/backend and the new replaceUserMetadata() page.

Have a look, and let me know if anything looks off. I also updated the todo list in the PR description with a few more items.

[SarahSoutoul]

@brunol95 left a docs review with some small fixes:

• Made consistent the phrase future major API version across the changes as some were using future major version
• Made consistent all of the deprecated properties changes to be consistent with rest of docs.
• Improved the wording of some of the text.

I noticed there was still a mention of client.users.updateUser() but from my understanding, it's fine to keep it as is cause we're not updating any publicMetadata or the other metadata properties. Is that correct?

[manovotny]

Pushed re-review fixes directly in 0886311.

• Expanded the deprecation guidance on updateUser()'s publicMetadata/privateMetadata/unsafeMetadata params to point to both updateUserMetadata() (partial/deep-merge) and replaceUserMetadata() (full replacement). The previous wording only mentioned the merge path, which would silently change behavior for anyone relying on updateUser()'s replace semantics.
• Dropped "API" from "future major API version" in update-user.mdx, core-3.mdx, and objects/user.mdx. These are SDK-level deprecations — they'll be removed in a future major SDK release (per clerk/javascript#8587) — and "API version" risked conflating that with the dated API versions documented elsewhere in this PR.
• Moved the > [!NOTE] deprecation callout to the top of the "Update user metadata" section on both user.ios.mdx and user.mdx, per Sarah's thread.

[brunol95]

I noticed there was still a mention of client.users.updateUser() but from my understanding, it's fine to keep it as is cause we're not updating any publicMetadata or the other metadata properties. Is that correct?

yep! client.users.updateUser() is still a valid method just can't be used for updating metadata.

[manovotny]

Pushed re-review fixes for the Organizations expansion directly in 2007d70.

• Fixed the ins line ranges on the organization example in the 2026-05-12 guide so replaceOrganizationMetadata()'s closing line highlights (same off-by-one as the user example fixed earlier).
• Corrected the guide intro — it claimed the dedicated metadata endpoints "provide deep-merge semantics," but the guide documents both PATCH (deep-merge) and PUT (full replace) endpoints. It now says which does which.
• Aligned updateOrganization()'s metadata deprecation wording with the updateUser() equivalents: bold format, both migration paths (updateOrganizationMetadata() for partial updates, replaceOrganizationMetadata() for full replacement), and "future major version" without "API."
• Unified the org metadata params type name as OrganizationMetadataParams on both org metadata reference pages — the new replace page and the existing update page had invented two different names for the same shape (clerk/javascript#8787 uses one type for both methods, matching how the user pages share UserMetadataParams).
• Added the full-replace TIP to updateOrganizationMetadata(), mirroring the one on updateUserMetadata().

Verified the org endpoint changes against clerk/clerk_go#18806 (metadata rejection on org PATCH at 2026-05-12) and the SDK claims against clerk/javascript#8787, clerk-ios#415, and clerk-android#650. Build and lint pass.

[manovotny]

Pushed two consistency fixes directly in d62c760.

• Capitalized "Organization" as a Clerk feature proper noun (per the STYLEGUIDE rule added in chore: standardize Clerk feature noun capitalization #3437) across this PR's org metadata content — the new rate-limit rows in system-limits.mdx, the 2026-05-12 guide, versioning.mdx, the Core 3 accordion, and replace-organization-metadata.mdx. Kept "membership" lowercase per the same rule. This brings the PR's new content in line with the standardization pass that already ran on the rest of the repo.
• Restored the 2026-05-12 SDK compatibility table in versioning.mdx to the @clerk/nextjs v7.5.2 or higher format the sibling version tables use — it had landed as bare version numbers (7.5.2), which read as exact-only. Verified every JS-ecosystem version against clerk/javascript, and the rest against their registries.

[manovotny]

@brunol95 I think this is good. When you're ready, remove the "do not merge" label and let it rip.