chore(backend): Deprecate metadata updates in organization update method

.changeset/deprecate-update-organization-metadata.md

@@ -0,0 +1,23 @@
+---
+'@clerk/backend': minor
+---
+
+Add `clerkClient.organizations.replaceOrganizationMetadata(organizationId, params)` for replacing an organization's metadata fields in full.
+
+Use `replaceOrganizationMetadata` when the provided metadata should become the complete value for that metadata field:
+
+```ts
+await clerkClient.organizations.replaceOrganizationMetadata(organizationId, {
+ publicMetadata: { plan: 'pro' },
+});
+```
+
+Use `clerkClient.organizations.updateOrganizationMetadata(organizationId, params)` when you want to partially update metadata with deep-merge semantics:
+
+```ts
+await clerkClient.organizations.updateOrganizationMetadata(organizationId, {
+ publicMetadata: { onboardingComplete: true },
+});
+```
+
+The `publicMetadata` and `privateMetadata` parameters on `clerkClient.organizations.updateOrganization()` are now deprecated. They continue to work, but new code should use `updateOrganizationMetadata()` for partial updates or `replaceOrganizationMetadata()` for full replacement.

packages/backend/src/api/__tests__/OrganizationApi.test.ts

@@ -1,5 +1,5 @@
 import { http, HttpResponse } from 'msw';
-import { describe, expect, expectTypeOf, it } from 'vitest';
+import { describe, expect, expectTypeOf, it, vi } from 'vitest';
 
 import { server, validateHeaders } from '../../mock-server';
 import { createBackendApiClient } from '../factory';
@@ -14,29 +14,199 @@ describe('OrganizationAPI', () => {
 
  const organizationId = 'org_123';
 
- const mockInvitation = {
- object: 'organization_invitation',
- id: 'orginv_1',
- email_address: 'one@example.com',
- role: 'org:member',
- role_name: 'Member',
- organization_id: organizationId,
- status: 'pending',
+ const mockOrgResponse = {
+ object: 'organization',
+ id: organizationId,
+ name: 'Test Org',
+ slug: 'test-org',
  public_metadata: {},
  private_metadata: {},
- url: null,
- created_at: 1640995200,
- updated_at: 1640995200,
- expires_at: 1643673600,
  };
 
+ describe('updateOrganization', () => {
+ it('calls PATCH /organizations/{id} when no metadata fields are provided', async () => {
+ const patchHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = await request.json();
+ expect(body).toEqual({ name: 'New Name' });
+ return HttpResponse.json(mockOrgResponse);
+ });
+
+ server.use(
+ http.patch(`https://api.clerk.test/v1/organizations/${organizationId}`, validateHeaders(patchHandler)),
+ );
+
+ const response = await apiClient.organizations.updateOrganization(organizationId, { name: 'New Name' });
+
+ expect(patchHandler).toHaveBeenCalledTimes(1);
+ expect(response.id).toBe(organizationId);
+ });
+
+ it('routes metadata to PUT /organizations/{id}/metadata when only metadata is provided', async () => {
+ const patchHandler = vi.fn(() => HttpResponse.json(mockOrgResponse));
+ const putHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ public_metadata: { foo: 'bar' },
+ });
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ public_metadata: { foo: 'bar' },
+ });
+ });
+
+ server.use(
+ http.patch(`https://api.clerk.test/v1/organizations/${organizationId}`, validateHeaders(patchHandler)),
+ http.put(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(putHandler)),
+ );
+
+ const response = await apiClient.organizations.updateOrganization(organizationId, {
+ publicMetadata: { foo: 'bar' },
+ });
+
+ expect(patchHandler).not.toHaveBeenCalled();
+ expect(putHandler).toHaveBeenCalledTimes(1);
+ expect(response.publicMetadata).toEqual({ foo: 'bar' });
+ });
+
+ it('splits mixed calls: PATCH for non-metadata, then PUT for metadata', async () => {
+ const calls: string[] = [];
+
+ const patchHandler = vi.fn(async ({ request }: { request: Request }) => {
+ calls.push('patch');
+ const body = await request.json();
+ expect(body).toEqual({ name: 'New Name' });
+ return HttpResponse.json(mockOrgResponse);
+ });
+
+ const putHandler = vi.fn(async ({ request }: { request: Request }) => {
+ calls.push('put');
+ const body = await request.json();
+ expect(body).toEqual({
+ public_metadata: { plan: 'pro' },
+ private_metadata: { invoice: 'inv_1' },
+ });
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ name: 'New Name',
+ public_metadata: { plan: 'pro' },
+ private_metadata: { invoice: 'inv_1' },
+ });
+ });
+
+ server.use(
+ http.patch(`https://api.clerk.test/v1/organizations/${organizationId}`, validateHeaders(patchHandler)),
+ http.put(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(putHandler)),
+ );
+
+ const response = await apiClient.organizations.updateOrganization(organizationId, {
+ name: 'New Name',
+ publicMetadata: { plan: 'pro' },
+ privateMetadata: { invoice: 'inv_1' },
+ });
+
+ expect(patchHandler).toHaveBeenCalledTimes(1);
+ expect(putHandler).toHaveBeenCalledTimes(1);
+ expect(calls).toEqual(['patch', 'put']);
+ expect(response.name).toBe('New Name');
+ expect(response.publicMetadata).toEqual({ plan: 'pro' });
+ });
+
+ it('passes only metadata fields that were explicitly provided to PUT', async () => {
+ const putHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = (await request.json()) as Record<string, unknown>;
+ expect(body.private_metadata).toEqual({ secret: 'value' });
+ expect(body).not.toHaveProperty('public_metadata');
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ private_metadata: { secret: 'value' },
+ });
+ });
+
+ server.use(
+ http.put(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(putHandler)),
+ );
+
+ await apiClient.organizations.updateOrganization(organizationId, {
+ privateMetadata: { secret: 'value' },
+ });
+
+ expect(putHandler).toHaveBeenCalledTimes(1);
+ });
+ });
+
+ describe('updateOrganizationMetadata', () => {
+ it('still hits PATCH /organizations/{id}/metadata (unchanged)', async () => {
+ const patchHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ public_metadata: { merge: true },
+ });
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ public_metadata: { merge: true },
+ });
+ });
+
+ server.use(
+ http.patch(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(patchHandler)),
+ );
+
+ await apiClient.organizations.updateOrganizationMetadata(organizationId, {
+ publicMetadata: { merge: true },
+ });
+
+ expect(patchHandler).toHaveBeenCalledTimes(1);
+ });
+ });
+
+ describe('replaceOrganizationMetadata', () => {
+ it('hits PUT /organizations/{id}/metadata', async () => {
+ const putHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ public_metadata: { replaced: true },
+ });
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ public_metadata: { replaced: true },
+ });
+ });
+
+ server.use(
+ http.put(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(putHandler)),
+ );
+
+ const response = await apiClient.organizations.replaceOrganizationMetadata(organizationId, {
+ publicMetadata: { replaced: true },
+ });
+
+ expect(putHandler).toHaveBeenCalledTimes(1);
+ expect(response.publicMetadata).toEqual({ replaced: true });
+ });
+ });
+
  describe('createOrganizationInvitationBulk', () => {
+ const mockInvitation = {
+ object: 'organization_invitation',
+ id: 'orginv_1',
+ email_address: 'one@example.com',
+ role: 'org:member',
+ role_name: 'Member',
+ organization_id: organizationId,
+ status: 'pending',
+ public_metadata: {},
+ private_metadata: {},
+ url: null,
+ created_at: 1640995200,
+ updated_at: 1640995200,
+ expires_at: 1643673600,
+ };
+
  it('returns a paginated { data, totalCount } response matching the Backend API shape', async () => {
  server.use(
  http.post(
  `https://api.clerk.test/v1/organizations/${organizationId}/invitations/bulk`,
  validateHeaders(async ({ request }) => {
- // The SDK should forward the invitations as a snake_cased array body.
  const body = (await request.json()) as Array<Record<string, unknown>>;
  expect(body).toHaveLength(2);
  expect(body[0]).toMatchObject({
@@ -58,15 +228,11 @@ describe('OrganizationAPI', () => {
  { emailAddress: 'two@example.com', role: 'org:member', inviterUserId: 'user_1' },
  ]);
 
- // The Backend API wraps bulk results in a paginated envelope, and the
- // deserializer surfaces it as `{ data, totalCount }`.
  expect(response.data).toHaveLength(2);
  expect(response.data[0].emailAddress).toBe('one@example.com');
  expect(response.data[0].organizationId).toBe(organizationId);
  expect(response.totalCount).toBe(2);
 
- // The declared return type must reflect that paginated shape, the same
- // way the sibling `getOrganizationInvitationList` does.
  expectTypeOf(response).toEqualTypeOf<PaginatedResourceResponse<OrganizationInvitation[]>>();
  });
  });

packages/backend/src/api/endpoints/OrganizationApi.ts

@@ -2,6 +2,7 @@ import type { ClerkPaginationRequest, OrganizationEnrollmentMode } from '@clerk/
 
 import { runtime } from '../../runtime';
 import { joinPaths } from '../../util/path';
+import { deprecated } from '../../util/shared';
 import type {
  Organization,
  OrganizationDomain,
@@ -45,7 +46,25 @@ type UpdateParams = {
  slug?: string;
  adminDeleteEnabled?: boolean;
  maxAllowedMemberships?: number;
-} & MetadataParams;
+
+ /**
+ * Metadata visible to your Frontend and Backend APIs.
+ *
+ * @deprecated Updating metadata via `updateOrganization` is deprecated. Use
+ * `updateOrganizationMetadata` for partial updates (deep merge) or
+ * `replaceOrganizationMetadata` for full replacement.
+ */
+ publicMetadata?: OrganizationPublicMetadata;
+
+ /**
+ * Metadata visible only to your Backend API.
+ *
+ * @deprecated Updating metadata via `updateOrganization` is deprecated. Use
+ * `updateOrganizationMetadata` for partial updates (deep merge) or
+ * `replaceOrganizationMetadata` for full replacement.
+ */
+ privateMetadata?: OrganizationPrivateMetadata;
+};
 
 type UpdateLogoParams = {
  file: Blob | File;
@@ -256,10 +275,38 @@ export class OrganizationAPI extends AbstractAPI {
 
  public async updateOrganization(organizationId: string, params: UpdateParams) {
  this.requireId(organizationId);
+
+ const { publicMetadata, privateMetadata, ...rest } = params;
+ const hasMetadata = publicMetadata !== undefined || privateMetadata !== undefined;
+ const hasRest = Object.keys(rest).length > 0;
+
+ if (hasMetadata) {
+ deprecated(
+ 'updateOrganization(organizationId, { publicMetadata | privateMetadata })',
+ 'Use updateOrganizationMetadata for partial updates (merge) or replaceOrganizationMetadata for full replacement.',
+ );
+ }
+
+ if (!hasMetadata) {
+ return this.request<Organization>({
+ method: 'PATCH',
+ path: joinPaths(basePath, organizationId),
+ bodyParams: rest,
+ });
+ }
+
+ if (hasRest) {
+ await this.request<Organization>({
+ method: 'PATCH',
+ path: joinPaths(basePath, organizationId),
+ bodyParams: rest,
+ });
+ }
+
  return this.request<Organization>({
- method: 'PATCH',
- path: joinPaths(basePath, organizationId),
- bodyParams: params,
+ method: 'PUT',
+ path: joinPaths(basePath, organizationId, 'metadata'),
+ bodyParams: { publicMetadata, privateMetadata },
  });
  }
 
@@ -298,6 +345,21 @@ export class OrganizationAPI extends AbstractAPI {
  });
  }
 
+ /**
+ * Replace an organization's metadata. Supplied fields are overwritten in full;
+ * fields omitted from `params` are left unchanged. Prefer
+ * `updateOrganizationMetadata` for partial updates with deep-merge semantics.
+ */
+ public async replaceOrganizationMetadata(organizationId: string, params: MetadataParams) {
+ this.requireId(organizationId);
+
+ return this.request<Organization>({
+ method: 'PUT',
+ path: joinPaths(basePath, organizationId, 'metadata'),
+ bodyParams: params,
+ });
+ }
+
  public async deleteOrganization(organizationId: string) {
  return this.request<Organization>({
  method: 'DELETE',

packages/backend/src/constants.ts

@@ -3,7 +3,7 @@ export const API_VERSION = 'v1';
 
 export const USER_AGENT = `${PACKAGE_NAME}@${PACKAGE_VERSION}`;
 export const MAX_CACHE_LAST_UPDATED_AT_SECONDS = 5 * 60;
-export const SUPPORTED_BAPI_VERSION = '2025-11-10';
+export const SUPPORTED_BAPI_VERSION = '2026-05-12';
 
 const Attributes = {
  AuthToken: '__clerkAuthToken',

packages/backend/src/tokens/__tests__/handshake.test.ts

@@ -447,7 +447,7 @@ describe('HandshakeService', () => {
 
  // Verify all required parameters are present
  expect(url.searchParams.get('redirect_url')).toBeDefined();
- expect(url.searchParams.get('__clerk_api_version')).toBe('2025-11-10');
+ expect(url.searchParams.get('__clerk_api_version')).toBe('2026-05-12');
  expect(url.searchParams.get(constants.QueryParameters.SuffixedCookies)).toMatch(/^(true|false)$/);
  expect(url.searchParams.get(constants.QueryParameters.HandshakeReason)).toBe('test-reason');
  });

packages/shared/src/internal/clerk-js/constants.ts

@@ -62,7 +62,7 @@ export const SIGN_UP_MODES = {
 } satisfies Record<string, SignUpModes>;
 
 // This is the currently supported version of the Frontend API
-export const SUPPORTED_FAPI_VERSION = '2025-11-10';
+export const SUPPORTED_FAPI_VERSION = '2026-05-12';
 
 export const CAPTCHA_ELEMENT_ID = 'clerk-captcha';
 export const CAPTCHA_INVISIBLE_CLASSNAME = 'clerk-invisible-captcha';

.changeset/deprecate-update-organization-metadata.md

@@ -0,0 +1,23 @@
+---
+'@clerk/backend': minor
+---
+
+Add `clerkClient.organizations.replaceOrganizationMetadata(organizationId, params)` for replacing an organization's metadata fields in full.
+
+Use `replaceOrganizationMetadata` when the provided metadata should become the complete value for that metadata field:
+
+```ts
+await clerkClient.organizations.replaceOrganizationMetadata(organizationId, {
+ publicMetadata: { plan: 'pro' },
+});
+```
+
+Use `clerkClient.organizations.updateOrganizationMetadata(organizationId, params)` when you want to partially update metadata with deep-merge semantics:
+
+```ts
+await clerkClient.organizations.updateOrganizationMetadata(organizationId, {
+ publicMetadata: { onboardingComplete: true },
+});
+```
+
+The `publicMetadata` and `privateMetadata` parameters on `clerkClient.organizations.updateOrganization()` are now deprecated. They continue to work, but new code should use `updateOrganizationMetadata()` for partial updates or `replaceOrganizationMetadata()` for full replacement.

packages/backend/src/api/__tests__/OrganizationApi.test.ts

@@ -1,5 +1,5 @@
 import { http, HttpResponse } from 'msw';
-import { describe, expect, expectTypeOf, it } from 'vitest';
+import { describe, expect, expectTypeOf, it, vi } from 'vitest';
 
 import { server, validateHeaders } from '../../mock-server';
 import { createBackendApiClient } from '../factory';
@@ -14,29 +14,199 @@ describe('OrganizationAPI', () => {
 
  const organizationId = 'org_123';
 
- const mockInvitation = {
- object: 'organization_invitation',
- id: 'orginv_1',
- email_address: 'one@example.com',
- role: 'org:member',
- role_name: 'Member',
- organization_id: organizationId,
- status: 'pending',
+ const mockOrgResponse = {
+ object: 'organization',
+ id: organizationId,
+ name: 'Test Org',
+ slug: 'test-org',
  public_metadata: {},
  private_metadata: {},
- url: null,
- created_at: 1640995200,
- updated_at: 1640995200,
- expires_at: 1643673600,
  };
 
+ describe('updateOrganization', () => {
+ it('calls PATCH /organizations/{id} when no metadata fields are provided', async () => {
+ const patchHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = await request.json();
+ expect(body).toEqual({ name: 'New Name' });
+ return HttpResponse.json(mockOrgResponse);
+ });
+
+ server.use(
+ http.patch(`https://api.clerk.test/v1/organizations/${organizationId}`, validateHeaders(patchHandler)),
+ );
+
+ const response = await apiClient.organizations.updateOrganization(organizationId, { name: 'New Name' });
+
+ expect(patchHandler).toHaveBeenCalledTimes(1);
+ expect(response.id).toBe(organizationId);
+ });
+
+ it('routes metadata to PUT /organizations/{id}/metadata when only metadata is provided', async () => {
+ const patchHandler = vi.fn(() => HttpResponse.json(mockOrgResponse));
+ const putHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ public_metadata: { foo: 'bar' },
+ });
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ public_metadata: { foo: 'bar' },
+ });
+ });
+
+ server.use(
+ http.patch(`https://api.clerk.test/v1/organizations/${organizationId}`, validateHeaders(patchHandler)),
+ http.put(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(putHandler)),
+ );
+
+ const response = await apiClient.organizations.updateOrganization(organizationId, {
+ publicMetadata: { foo: 'bar' },
+ });
+
+ expect(patchHandler).not.toHaveBeenCalled();
+ expect(putHandler).toHaveBeenCalledTimes(1);
+ expect(response.publicMetadata).toEqual({ foo: 'bar' });
+ });
+
+ it('splits mixed calls: PATCH for non-metadata, then PUT for metadata', async () => {
+ const calls: string[] = [];
+
+ const patchHandler = vi.fn(async ({ request }: { request: Request }) => {
+ calls.push('patch');
+ const body = await request.json();
+ expect(body).toEqual({ name: 'New Name' });
+ return HttpResponse.json(mockOrgResponse);
+ });
+
+ const putHandler = vi.fn(async ({ request }: { request: Request }) => {
+ calls.push('put');
+ const body = await request.json();
+ expect(body).toEqual({
+ public_metadata: { plan: 'pro' },
+ private_metadata: { invoice: 'inv_1' },
+ });
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ name: 'New Name',
+ public_metadata: { plan: 'pro' },
+ private_metadata: { invoice: 'inv_1' },
+ });
+ });
+
+ server.use(
+ http.patch(`https://api.clerk.test/v1/organizations/${organizationId}`, validateHeaders(patchHandler)),
+ http.put(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(putHandler)),
+ );
+
+ const response = await apiClient.organizations.updateOrganization(organizationId, {
+ name: 'New Name',
+ publicMetadata: { plan: 'pro' },
+ privateMetadata: { invoice: 'inv_1' },
+ });
+
+ expect(patchHandler).toHaveBeenCalledTimes(1);
+ expect(putHandler).toHaveBeenCalledTimes(1);
+ expect(calls).toEqual(['patch', 'put']);
+ expect(response.name).toBe('New Name');
+ expect(response.publicMetadata).toEqual({ plan: 'pro' });
+ });
+
+ it('passes only metadata fields that were explicitly provided to PUT', async () => {
+ const putHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = (await request.json()) as Record<string, unknown>;
+ expect(body.private_metadata).toEqual({ secret: 'value' });
+ expect(body).not.toHaveProperty('public_metadata');
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ private_metadata: { secret: 'value' },
+ });
+ });
+
+ server.use(
+ http.put(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(putHandler)),
+ );
+
+ await apiClient.organizations.updateOrganization(organizationId, {
+ privateMetadata: { secret: 'value' },
+ });
+
+ expect(putHandler).toHaveBeenCalledTimes(1);
+ });
+ });
+
+ describe('updateOrganizationMetadata', () => {
+ it('still hits PATCH /organizations/{id}/metadata (unchanged)', async () => {
+ const patchHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ public_metadata: { merge: true },
+ });
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ public_metadata: { merge: true },
+ });
+ });
+
+ server.use(
+ http.patch(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(patchHandler)),
+ );
+
+ await apiClient.organizations.updateOrganizationMetadata(organizationId, {
+ publicMetadata: { merge: true },
+ });
+
+ expect(patchHandler).toHaveBeenCalledTimes(1);
+ });
+ });
+
+ describe('replaceOrganizationMetadata', () => {
+ it('hits PUT /organizations/{id}/metadata', async () => {
+ const putHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ public_metadata: { replaced: true },
+ });
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ public_metadata: { replaced: true },
+ });
+ });
+
+ server.use(
+ http.put(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(putHandler)),
+ );
+
+ const response = await apiClient.organizations.replaceOrganizationMetadata(organizationId, {
+ publicMetadata: { replaced: true },
+ });
+
+ expect(putHandler).toHaveBeenCalledTimes(1);
+ expect(response.publicMetadata).toEqual({ replaced: true });
+ });
+ });
+
  describe('createOrganizationInvitationBulk', () => {
+ const mockInvitation = {
+ object: 'organization_invitation',
+ id: 'orginv_1',
+ email_address: 'one@example.com',
+ role: 'org:member',
+ role_name: 'Member',
+ organization_id: organizationId,
+ status: 'pending',
+ public_metadata: {},
+ private_metadata: {},
+ url: null,
+ created_at: 1640995200,
+ updated_at: 1640995200,
+ expires_at: 1643673600,
+ };
+
  it('returns a paginated { data, totalCount } response matching the Backend API shape', async () => {
  server.use(
  http.post(
  `https://api.clerk.test/v1/organizations/${organizationId}/invitations/bulk`,
  validateHeaders(async ({ request }) => {
- // The SDK should forward the invitations as a snake_cased array body.
  const body = (await request.json()) as Array<Record<string, unknown>>;
  expect(body).toHaveLength(2);
  expect(body[0]).toMatchObject({
@@ -58,15 +228,11 @@ describe('OrganizationAPI', () => {
  { emailAddress: 'two@example.com', role: 'org:member', inviterUserId: 'user_1' },
  ]);
 
- // The Backend API wraps bulk results in a paginated envelope, and the
- // deserializer surfaces it as `{ data, totalCount }`.
  expect(response.data).toHaveLength(2);
  expect(response.data[0].emailAddress).toBe('one@example.com');
  expect(response.data[0].organizationId).toBe(organizationId);
  expect(response.totalCount).toBe(2);
 
- // The declared return type must reflect that paginated shape, the same
- // way the sibling `getOrganizationInvitationList` does.
  expectTypeOf(response).toEqualTypeOf<PaginatedResourceResponse<OrganizationInvitation[]>>();
  });
  });

packages/backend/src/api/endpoints/OrganizationApi.ts

@@ -2,6 +2,7 @@ import type { ClerkPaginationRequest, OrganizationEnrollmentMode } from '@clerk/
 
 import { runtime } from '../../runtime';
 import { joinPaths } from '../../util/path';
+import { deprecated } from '../../util/shared';
 import type {
  Organization,
  OrganizationDomain,
@@ -45,7 +46,25 @@ type UpdateParams = {
  slug?: string;
  adminDeleteEnabled?: boolean;
  maxAllowedMemberships?: number;
-} & MetadataParams;
+
+ /**
+ * Metadata visible to your Frontend and Backend APIs.
+ *
+ * @deprecated Updating metadata via `updateOrganization` is deprecated. Use
+ * `updateOrganizationMetadata` for partial updates (deep merge) or
+ * `replaceOrganizationMetadata` for full replacement.
+ */
+ publicMetadata?: OrganizationPublicMetadata;
+
+ /**
+ * Metadata visible only to your Backend API.
+ *
+ * @deprecated Updating metadata via `updateOrganization` is deprecated. Use
+ * `updateOrganizationMetadata` for partial updates (deep merge) or
+ * `replaceOrganizationMetadata` for full replacement.
+ */
+ privateMetadata?: OrganizationPrivateMetadata;
+};
 
 type UpdateLogoParams = {
  file: Blob | File;
@@ -256,10 +275,38 @@ export class OrganizationAPI extends AbstractAPI {
 
  public async updateOrganization(organizationId: string, params: UpdateParams) {
  this.requireId(organizationId);
+
+ const { publicMetadata, privateMetadata, ...rest } = params;
+ const hasMetadata = publicMetadata !== undefined || privateMetadata !== undefined;
+ const hasRest = Object.keys(rest).length > 0;
+
+ if (hasMetadata) {
+ deprecated(
+ 'updateOrganization(organizationId, { publicMetadata | privateMetadata })',
+ 'Use updateOrganizationMetadata for partial updates (merge) or replaceOrganizationMetadata for full replacement.',
+ );
+ }
+
+ if (!hasMetadata) {
+ return this.request<Organization>({
+ method: 'PATCH',
+ path: joinPaths(basePath, organizationId),
+ bodyParams: rest,
+ });
+ }
+
+ if (hasRest) {
+ await this.request<Organization>({
+ method: 'PATCH',
+ path: joinPaths(basePath, organizationId),
+ bodyParams: rest,
+ });
+ }
+
  return this.request<Organization>({
- method: 'PATCH',
- path: joinPaths(basePath, organizationId),
- bodyParams: params,
+ method: 'PUT',
+ path: joinPaths(basePath, organizationId, 'metadata'),
+ bodyParams: { publicMetadata, privateMetadata },
  });
  }
 
@@ -298,6 +345,21 @@ export class OrganizationAPI extends AbstractAPI {
  });
  }
 
+ /**
+ * Replace an organization's metadata. Supplied fields are overwritten in full;
+ * fields omitted from `params` are left unchanged. Prefer
+ * `updateOrganizationMetadata` for partial updates with deep-merge semantics.
+ */
+ public async replaceOrganizationMetadata(organizationId: string, params: MetadataParams) {
+ this.requireId(organizationId);
+
+ return this.request<Organization>({
+ method: 'PUT',
+ path: joinPaths(basePath, organizationId, 'metadata'),
+ bodyParams: params,
+ });
+ }
+
  public async deleteOrganization(organizationId: string) {
  return this.request<Organization>({
  method: 'DELETE',

packages/backend/src/constants.ts

@@ -3,7 +3,7 @@ export const API_VERSION = 'v1';
 
 export const USER_AGENT = `${PACKAGE_NAME}@${PACKAGE_VERSION}`;
 export const MAX_CACHE_LAST_UPDATED_AT_SECONDS = 5 * 60;
-export const SUPPORTED_BAPI_VERSION = '2025-11-10';
+export const SUPPORTED_BAPI_VERSION = '2026-05-12';
 
 const Attributes = {
  AuthToken: '__clerkAuthToken',

packages/backend/src/tokens/__tests__/handshake.test.ts

@@ -447,7 +447,7 @@ describe('HandshakeService', () => {
 
  // Verify all required parameters are present
  expect(url.searchParams.get('redirect_url')).toBeDefined();
- expect(url.searchParams.get('__clerk_api_version')).toBe('2025-11-10');
+ expect(url.searchParams.get('__clerk_api_version')).toBe('2026-05-12');
  expect(url.searchParams.get(constants.QueryParameters.SuffixedCookies)).toMatch(/^(true|false)$/);
  expect(url.searchParams.get(constants.QueryParameters.HandshakeReason)).toBe('test-reason');
  });

packages/shared/src/internal/clerk-js/constants.ts

@@ -62,7 +62,7 @@ export const SIGN_UP_MODES = {
 } satisfies Record<string, SignUpModes>;
 
 // This is the currently supported version of the Frontend API
-export const SUPPORTED_FAPI_VERSION = '2025-11-10';
+export const SUPPORTED_FAPI_VERSION = '2026-05-12';
 
 export const CAPTCHA_ELEMENT_ID = 'clerk-captcha';
 export const CAPTCHA_INVISIBLE_CLASSNAME = 'clerk-invisible-captcha';

.changeset/deprecate-update-organization-metadata.md

@@ -0,0 +1,23 @@
+---
+'@clerk/backend': minor
+---
+
+Add `clerkClient.organizations.replaceOrganizationMetadata(organizationId, params)` for replacing an organization's metadata fields in full.
+
+Use `replaceOrganizationMetadata` when the provided metadata should become the complete value for that metadata field:
+
+```ts
+await clerkClient.organizations.replaceOrganizationMetadata(organizationId, {
+ publicMetadata: { plan: 'pro' },
+});
+```
+
+Use `clerkClient.organizations.updateOrganizationMetadata(organizationId, params)` when you want to partially update metadata with deep-merge semantics:
+
+```ts
+await clerkClient.organizations.updateOrganizationMetadata(organizationId, {
+ publicMetadata: { onboardingComplete: true },
+});
+```
+
+The `publicMetadata` and `privateMetadata` parameters on `clerkClient.organizations.updateOrganization()` are now deprecated. They continue to work, but new code should use `updateOrganizationMetadata()` for partial updates or `replaceOrganizationMetadata()` for full replacement.

packages/backend/src/api/__tests__/OrganizationApi.test.ts

@@ -1,5 +1,5 @@
 import { http, HttpResponse } from 'msw';
-import { describe, expect, expectTypeOf, it } from 'vitest';
+import { describe, expect, expectTypeOf, it, vi } from 'vitest';
 
 import { server, validateHeaders } from '../../mock-server';
 import { createBackendApiClient } from '../factory';
@@ -14,29 +14,199 @@ describe('OrganizationAPI', () => {
 
  const organizationId = 'org_123';
 
- const mockInvitation = {
- object: 'organization_invitation',
- id: 'orginv_1',
- email_address: 'one@example.com',
- role: 'org:member',
- role_name: 'Member',
- organization_id: organizationId,
- status: 'pending',
+ const mockOrgResponse = {
+ object: 'organization',
+ id: organizationId,
+ name: 'Test Org',
+ slug: 'test-org',
  public_metadata: {},
  private_metadata: {},
- url: null,
- created_at: 1640995200,
- updated_at: 1640995200,
- expires_at: 1643673600,
  };
 
+ describe('updateOrganization', () => {
+ it('calls PATCH /organizations/{id} when no metadata fields are provided', async () => {
+ const patchHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = await request.json();
+ expect(body).toEqual({ name: 'New Name' });
+ return HttpResponse.json(mockOrgResponse);
+ });
+
+ server.use(
+ http.patch(`https://api.clerk.test/v1/organizations/${organizationId}`, validateHeaders(patchHandler)),
+ );
+
+ const response = await apiClient.organizations.updateOrganization(organizationId, { name: 'New Name' });
+
+ expect(patchHandler).toHaveBeenCalledTimes(1);
+ expect(response.id).toBe(organizationId);
+ });
+
+ it('routes metadata to PUT /organizations/{id}/metadata when only metadata is provided', async () => {
+ const patchHandler = vi.fn(() => HttpResponse.json(mockOrgResponse));
+ const putHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ public_metadata: { foo: 'bar' },
+ });
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ public_metadata: { foo: 'bar' },
+ });
+ });
+
+ server.use(
+ http.patch(`https://api.clerk.test/v1/organizations/${organizationId}`, validateHeaders(patchHandler)),
+ http.put(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(putHandler)),
+ );
+
+ const response = await apiClient.organizations.updateOrganization(organizationId, {
+ publicMetadata: { foo: 'bar' },
+ });
+
+ expect(patchHandler).not.toHaveBeenCalled();
+ expect(putHandler).toHaveBeenCalledTimes(1);
+ expect(response.publicMetadata).toEqual({ foo: 'bar' });
+ });
+
+ it('splits mixed calls: PATCH for non-metadata, then PUT for metadata', async () => {
+ const calls: string[] = [];
+
+ const patchHandler = vi.fn(async ({ request }: { request: Request }) => {
+ calls.push('patch');
+ const body = await request.json();
+ expect(body).toEqual({ name: 'New Name' });
+ return HttpResponse.json(mockOrgResponse);
+ });
+
+ const putHandler = vi.fn(async ({ request }: { request: Request }) => {
+ calls.push('put');
+ const body = await request.json();
+ expect(body).toEqual({
+ public_metadata: { plan: 'pro' },
+ private_metadata: { invoice: 'inv_1' },
+ });
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ name: 'New Name',
+ public_metadata: { plan: 'pro' },
+ private_metadata: { invoice: 'inv_1' },
+ });
+ });
+
+ server.use(
+ http.patch(`https://api.clerk.test/v1/organizations/${organizationId}`, validateHeaders(patchHandler)),
+ http.put(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(putHandler)),
+ );
+
+ const response = await apiClient.organizations.updateOrganization(organizationId, {
+ name: 'New Name',
+ publicMetadata: { plan: 'pro' },
+ privateMetadata: { invoice: 'inv_1' },
+ });
+
+ expect(patchHandler).toHaveBeenCalledTimes(1);
+ expect(putHandler).toHaveBeenCalledTimes(1);
+ expect(calls).toEqual(['patch', 'put']);
+ expect(response.name).toBe('New Name');
+ expect(response.publicMetadata).toEqual({ plan: 'pro' });
+ });
+
+ it('passes only metadata fields that were explicitly provided to PUT', async () => {
+ const putHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = (await request.json()) as Record<string, unknown>;
+ expect(body.private_metadata).toEqual({ secret: 'value' });
+ expect(body).not.toHaveProperty('public_metadata');
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ private_metadata: { secret: 'value' },
+ });
+ });
+
+ server.use(
+ http.put(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(putHandler)),
+ );
+
+ await apiClient.organizations.updateOrganization(organizationId, {
+ privateMetadata: { secret: 'value' },
+ });
+
+ expect(putHandler).toHaveBeenCalledTimes(1);
+ });
+ });
+
+ describe('updateOrganizationMetadata', () => {
+ it('still hits PATCH /organizations/{id}/metadata (unchanged)', async () => {
+ const patchHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ public_metadata: { merge: true },
+ });
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ public_metadata: { merge: true },
+ });
+ });
+
+ server.use(
+ http.patch(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(patchHandler)),
+ );
+
+ await apiClient.organizations.updateOrganizationMetadata(organizationId, {
+ publicMetadata: { merge: true },
+ });
+
+ expect(patchHandler).toHaveBeenCalledTimes(1);
+ });
+ });
+
+ describe('replaceOrganizationMetadata', () => {
+ it('hits PUT /organizations/{id}/metadata', async () => {
+ const putHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ public_metadata: { replaced: true },
+ });
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ public_metadata: { replaced: true },
+ });
+ });
+
+ server.use(
+ http.put(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(putHandler)),
+ );
+
+ const response = await apiClient.organizations.replaceOrganizationMetadata(organizationId, {
+ publicMetadata: { replaced: true },
+ });
+
+ expect(putHandler).toHaveBeenCalledTimes(1);
+ expect(response.publicMetadata).toEqual({ replaced: true });
+ });
+ });
+
  describe('createOrganizationInvitationBulk', () => {
+ const mockInvitation = {
+ object: 'organization_invitation',
+ id: 'orginv_1',
+ email_address: 'one@example.com',
+ role: 'org:member',
+ role_name: 'Member',
+ organization_id: organizationId,
+ status: 'pending',
+ public_metadata: {},
+ private_metadata: {},
+ url: null,
+ created_at: 1640995200,
+ updated_at: 1640995200,
+ expires_at: 1643673600,
+ };
+
  it('returns a paginated { data, totalCount } response matching the Backend API shape', async () => {
  server.use(
  http.post(
  `https://api.clerk.test/v1/organizations/${organizationId}/invitations/bulk`,
  validateHeaders(async ({ request }) => {
- // The SDK should forward the invitations as a snake_cased array body.
  const body = (await request.json()) as Array<Record<string, unknown>>;
  expect(body).toHaveLength(2);
  expect(body[0]).toMatchObject({
@@ -58,15 +228,11 @@ describe('OrganizationAPI', () => {
  { emailAddress: 'two@example.com', role: 'org:member', inviterUserId: 'user_1' },
  ]);
 
- // The Backend API wraps bulk results in a paginated envelope, and the
- // deserializer surfaces it as `{ data, totalCount }`.
  expect(response.data).toHaveLength(2);
  expect(response.data[0].emailAddress).toBe('one@example.com');
  expect(response.data[0].organizationId).toBe(organizationId);
  expect(response.totalCount).toBe(2);
 
- // The declared return type must reflect that paginated shape, the same
- // way the sibling `getOrganizationInvitationList` does.
  expectTypeOf(response).toEqualTypeOf<PaginatedResourceResponse<OrganizationInvitation[]>>();
  });
  });

packages/backend/src/api/endpoints/OrganizationApi.ts

@@ -2,6 +2,7 @@ import type { ClerkPaginationRequest, OrganizationEnrollmentMode } from '@clerk/
 
 import { runtime } from '../../runtime';
 import { joinPaths } from '../../util/path';
+import { deprecated } from '../../util/shared';
 import type {
  Organization,
  OrganizationDomain,
@@ -45,7 +46,25 @@ type UpdateParams = {
  slug?: string;
  adminDeleteEnabled?: boolean;
  maxAllowedMemberships?: number;
-} & MetadataParams;
+
+ /**
+ * Metadata visible to your Frontend and Backend APIs.
+ *
+ * @deprecated Updating metadata via `updateOrganization` is deprecated. Use
+ * `updateOrganizationMetadata` for partial updates (deep merge) or
+ * `replaceOrganizationMetadata` for full replacement.
+ */
+ publicMetadata?: OrganizationPublicMetadata;
+
+ /**
+ * Metadata visible only to your Backend API.
+ *
+ * @deprecated Updating metadata via `updateOrganization` is deprecated. Use
+ * `updateOrganizationMetadata` for partial updates (deep merge) or
+ * `replaceOrganizationMetadata` for full replacement.
+ */
+ privateMetadata?: OrganizationPrivateMetadata;
+};
 
 type UpdateLogoParams = {
  file: Blob | File;
@@ -256,10 +275,38 @@ export class OrganizationAPI extends AbstractAPI {
 
  public async updateOrganization(organizationId: string, params: UpdateParams) {
  this.requireId(organizationId);
+
+ const { publicMetadata, privateMetadata, ...rest } = params;
+ const hasMetadata = publicMetadata !== undefined || privateMetadata !== undefined;
+ const hasRest = Object.keys(rest).length > 0;
+
+ if (hasMetadata) {
+ deprecated(
+ 'updateOrganization(organizationId, { publicMetadata | privateMetadata })',
+ 'Use updateOrganizationMetadata for partial updates (merge) or replaceOrganizationMetadata for full replacement.',
+ );
+ }
+
+ if (!hasMetadata) {
+ return this.request<Organization>({
+ method: 'PATCH',
+ path: joinPaths(basePath, organizationId),
+ bodyParams: rest,
+ });
+ }
+
+ if (hasRest) {
+ await this.request<Organization>({
+ method: 'PATCH',
+ path: joinPaths(basePath, organizationId),
+ bodyParams: rest,
+ });
+ }
+
  return this.request<Organization>({
- method: 'PATCH',
- path: joinPaths(basePath, organizationId),
- bodyParams: params,
+ method: 'PUT',
+ path: joinPaths(basePath, organizationId, 'metadata'),
+ bodyParams: { publicMetadata, privateMetadata },
  });
  }
 
@@ -298,6 +345,21 @@ export class OrganizationAPI extends AbstractAPI {
  });
  }
 
+ /**
+ * Replace an organization's metadata. Supplied fields are overwritten in full;
+ * fields omitted from `params` are left unchanged. Prefer
+ * `updateOrganizationMetadata` for partial updates with deep-merge semantics.
+ */
+ public async replaceOrganizationMetadata(organizationId: string, params: MetadataParams) {
+ this.requireId(organizationId);
+
+ return this.request<Organization>({
+ method: 'PUT',
+ path: joinPaths(basePath, organizationId, 'metadata'),
+ bodyParams: params,
+ });
+ }
+
  public async deleteOrganization(organizationId: string) {
  return this.request<Organization>({
  method: 'DELETE',

packages/backend/src/constants.ts

@@ -3,7 +3,7 @@ export const API_VERSION = 'v1';
 
 export const USER_AGENT = `${PACKAGE_NAME}@${PACKAGE_VERSION}`;
 export const MAX_CACHE_LAST_UPDATED_AT_SECONDS = 5 * 60;
-export const SUPPORTED_BAPI_VERSION = '2025-11-10';
+export const SUPPORTED_BAPI_VERSION = '2026-05-12';
 
 const Attributes = {
  AuthToken: '__clerkAuthToken',

packages/backend/src/tokens/__tests__/handshake.test.ts

@@ -447,7 +447,7 @@ describe('HandshakeService', () => {
 
  // Verify all required parameters are present
  expect(url.searchParams.get('redirect_url')).toBeDefined();
- expect(url.searchParams.get('__clerk_api_version')).toBe('2025-11-10');
+ expect(url.searchParams.get('__clerk_api_version')).toBe('2026-05-12');
  expect(url.searchParams.get(constants.QueryParameters.SuffixedCookies)).toMatch(/^(true|false)$/);
  expect(url.searchParams.get(constants.QueryParameters.HandshakeReason)).toBe('test-reason');
  });

packages/shared/src/internal/clerk-js/constants.ts

@@ -62,7 +62,7 @@ export const SIGN_UP_MODES = {
 } satisfies Record<string, SignUpModes>;
 
 // This is the currently supported version of the Frontend API
-export const SUPPORTED_FAPI_VERSION = '2025-11-10';
+export const SUPPORTED_FAPI_VERSION = '2026-05-12';
 
 export const CAPTCHA_ELEMENT_ID = 'clerk-captcha';
 export const CAPTCHA_INVISIBLE_CLASSNAME = 'clerk-invisible-captcha';

.changeset/deprecate-update-organization-metadata.md

@@ -0,0 +1,23 @@
+---
+'@clerk/backend': minor
+---
+
+Add `clerkClient.organizations.replaceOrganizationMetadata(organizationId, params)` for replacing an organization's metadata fields in full.
+
+Use `replaceOrganizationMetadata` when the provided metadata should become the complete value for that metadata field:
+
+```ts
+await clerkClient.organizations.replaceOrganizationMetadata(organizationId, {
+ publicMetadata: { plan: 'pro' },
+});
+```
+
+Use `clerkClient.organizations.updateOrganizationMetadata(organizationId, params)` when you want to partially update metadata with deep-merge semantics:
+
+```ts
+await clerkClient.organizations.updateOrganizationMetadata(organizationId, {
+ publicMetadata: { onboardingComplete: true },
+});
+```
+
+The `publicMetadata` and `privateMetadata` parameters on `clerkClient.organizations.updateOrganization()` are now deprecated. They continue to work, but new code should use `updateOrganizationMetadata()` for partial updates or `replaceOrganizationMetadata()` for full replacement.

packages/backend/src/api/__tests__/OrganizationApi.test.ts

@@ -1,5 +1,5 @@
 import { http, HttpResponse } from 'msw';
-import { describe, expect, expectTypeOf, it } from 'vitest';
+import { describe, expect, expectTypeOf, it, vi } from 'vitest';
 
 import { server, validateHeaders } from '../../mock-server';
 import { createBackendApiClient } from '../factory';
@@ -14,29 +14,199 @@ describe('OrganizationAPI', () => {
 
  const organizationId = 'org_123';
 
- const mockInvitation = {
- object: 'organization_invitation',
- id: 'orginv_1',
- email_address: 'one@example.com',
- role: 'org:member',
- role_name: 'Member',
- organization_id: organizationId,
- status: 'pending',
+ const mockOrgResponse = {
+ object: 'organization',
+ id: organizationId,
+ name: 'Test Org',
+ slug: 'test-org',
  public_metadata: {},
  private_metadata: {},
- url: null,
- created_at: 1640995200,
- updated_at: 1640995200,
- expires_at: 1643673600,
  };
 
+ describe('updateOrganization', () => {
+ it('calls PATCH /organizations/{id} when no metadata fields are provided', async () => {
+ const patchHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = await request.json();
+ expect(body).toEqual({ name: 'New Name' });
+ return HttpResponse.json(mockOrgResponse);
+ });
+
+ server.use(
+ http.patch(`https://api.clerk.test/v1/organizations/${organizationId}`, validateHeaders(patchHandler)),
+ );
+
+ const response = await apiClient.organizations.updateOrganization(organizationId, { name: 'New Name' });
+
+ expect(patchHandler).toHaveBeenCalledTimes(1);
+ expect(response.id).toBe(organizationId);
+ });
+
+ it('routes metadata to PUT /organizations/{id}/metadata when only metadata is provided', async () => {
+ const patchHandler = vi.fn(() => HttpResponse.json(mockOrgResponse));
+ const putHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ public_metadata: { foo: 'bar' },
+ });
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ public_metadata: { foo: 'bar' },
+ });
+ });
+
+ server.use(
+ http.patch(`https://api.clerk.test/v1/organizations/${organizationId}`, validateHeaders(patchHandler)),
+ http.put(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(putHandler)),
+ );
+
+ const response = await apiClient.organizations.updateOrganization(organizationId, {
+ publicMetadata: { foo: 'bar' },
+ });
+
+ expect(patchHandler).not.toHaveBeenCalled();
+ expect(putHandler).toHaveBeenCalledTimes(1);
+ expect(response.publicMetadata).toEqual({ foo: 'bar' });
+ });
+
+ it('splits mixed calls: PATCH for non-metadata, then PUT for metadata', async () => {
+ const calls: string[] = [];
+
+ const patchHandler = vi.fn(async ({ request }: { request: Request }) => {
+ calls.push('patch');
+ const body = await request.json();
+ expect(body).toEqual({ name: 'New Name' });
+ return HttpResponse.json(mockOrgResponse);
+ });
+
+ const putHandler = vi.fn(async ({ request }: { request: Request }) => {
+ calls.push('put');
+ const body = await request.json();
+ expect(body).toEqual({
+ public_metadata: { plan: 'pro' },
+ private_metadata: { invoice: 'inv_1' },
+ });
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ name: 'New Name',
+ public_metadata: { plan: 'pro' },
+ private_metadata: { invoice: 'inv_1' },
+ });
+ });
+
+ server.use(
+ http.patch(`https://api.clerk.test/v1/organizations/${organizationId}`, validateHeaders(patchHandler)),
+ http.put(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(putHandler)),
+ );
+
+ const response = await apiClient.organizations.updateOrganization(organizationId, {
+ name: 'New Name',
+ publicMetadata: { plan: 'pro' },
+ privateMetadata: { invoice: 'inv_1' },
+ });
+
+ expect(patchHandler).toHaveBeenCalledTimes(1);
+ expect(putHandler).toHaveBeenCalledTimes(1);
+ expect(calls).toEqual(['patch', 'put']);
+ expect(response.name).toBe('New Name');
+ expect(response.publicMetadata).toEqual({ plan: 'pro' });
+ });
+
+ it('passes only metadata fields that were explicitly provided to PUT', async () => {
+ const putHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = (await request.json()) as Record<string, unknown>;
+ expect(body.private_metadata).toEqual({ secret: 'value' });
+ expect(body).not.toHaveProperty('public_metadata');
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ private_metadata: { secret: 'value' },
+ });
+ });
+
+ server.use(
+ http.put(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(putHandler)),
+ );
+
+ await apiClient.organizations.updateOrganization(organizationId, {
+ privateMetadata: { secret: 'value' },
+ });
+
+ expect(putHandler).toHaveBeenCalledTimes(1);
+ });
+ });
+
+ describe('updateOrganizationMetadata', () => {
+ it('still hits PATCH /organizations/{id}/metadata (unchanged)', async () => {
+ const patchHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ public_metadata: { merge: true },
+ });
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ public_metadata: { merge: true },
+ });
+ });
+
+ server.use(
+ http.patch(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(patchHandler)),
+ );
+
+ await apiClient.organizations.updateOrganizationMetadata(organizationId, {
+ publicMetadata: { merge: true },
+ });
+
+ expect(patchHandler).toHaveBeenCalledTimes(1);
+ });
+ });
+
+ describe('replaceOrganizationMetadata', () => {
+ it('hits PUT /organizations/{id}/metadata', async () => {
+ const putHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ public_metadata: { replaced: true },
+ });
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ public_metadata: { replaced: true },
+ });
+ });
+
+ server.use(
+ http.put(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(putHandler)),
+ );
+
+ const response = await apiClient.organizations.replaceOrganizationMetadata(organizationId, {
+ publicMetadata: { replaced: true },
+ });
+
+ expect(putHandler).toHaveBeenCalledTimes(1);
+ expect(response.publicMetadata).toEqual({ replaced: true });
+ });
+ });
+
  describe('createOrganizationInvitationBulk', () => {
+ const mockInvitation = {
+ object: 'organization_invitation',
+ id: 'orginv_1',
+ email_address: 'one@example.com',
+ role: 'org:member',
+ role_name: 'Member',
+ organization_id: organizationId,
+ status: 'pending',
+ public_metadata: {},
+ private_metadata: {},
+ url: null,
+ created_at: 1640995200,
+ updated_at: 1640995200,
+ expires_at: 1643673600,
+ };
+
  it('returns a paginated { data, totalCount } response matching the Backend API shape', async () => {
  server.use(
  http.post(
  `https://api.clerk.test/v1/organizations/${organizationId}/invitations/bulk`,
  validateHeaders(async ({ request }) => {
- // The SDK should forward the invitations as a snake_cased array body.
  const body = (await request.json()) as Array<Record<string, unknown>>;
  expect(body).toHaveLength(2);
  expect(body[0]).toMatchObject({
@@ -58,15 +228,11 @@ describe('OrganizationAPI', () => {
  { emailAddress: 'two@example.com', role: 'org:member', inviterUserId: 'user_1' },
  ]);
 
- // The Backend API wraps bulk results in a paginated envelope, and the
- // deserializer surfaces it as `{ data, totalCount }`.
  expect(response.data).toHaveLength(2);
  expect(response.data[0].emailAddress).toBe('one@example.com');
  expect(response.data[0].organizationId).toBe(organizationId);
  expect(response.totalCount).toBe(2);
 
- // The declared return type must reflect that paginated shape, the same
- // way the sibling `getOrganizationInvitationList` does.
  expectTypeOf(response).toEqualTypeOf<PaginatedResourceResponse<OrganizationInvitation[]>>();
  });
  });

packages/backend/src/api/endpoints/OrganizationApi.ts

@@ -2,6 +2,7 @@ import type { ClerkPaginationRequest, OrganizationEnrollmentMode } from '@clerk/
 
 import { runtime } from '../../runtime';
 import { joinPaths } from '../../util/path';
+import { deprecated } from '../../util/shared';
 import type {
  Organization,
  OrganizationDomain,
@@ -45,7 +46,25 @@ type UpdateParams = {
  slug?: string;
  adminDeleteEnabled?: boolean;
  maxAllowedMemberships?: number;
-} & MetadataParams;
+
+ /**
+ * Metadata visible to your Frontend and Backend APIs.
+ *
+ * @deprecated Updating metadata via `updateOrganization` is deprecated. Use
+ * `updateOrganizationMetadata` for partial updates (deep merge) or
+ * `replaceOrganizationMetadata` for full replacement.
+ */
+ publicMetadata?: OrganizationPublicMetadata;
+
+ /**
+ * Metadata visible only to your Backend API.
+ *
+ * @deprecated Updating metadata via `updateOrganization` is deprecated. Use
+ * `updateOrganizationMetadata` for partial updates (deep merge) or
+ * `replaceOrganizationMetadata` for full replacement.
+ */
+ privateMetadata?: OrganizationPrivateMetadata;
+};
 
 type UpdateLogoParams = {
  file: Blob | File;
@@ -256,10 +275,38 @@ export class OrganizationAPI extends AbstractAPI {
 
  public async updateOrganization(organizationId: string, params: UpdateParams) {
  this.requireId(organizationId);
+
+ const { publicMetadata, privateMetadata, ...rest } = params;
+ const hasMetadata = publicMetadata !== undefined || privateMetadata !== undefined;
+ const hasRest = Object.keys(rest).length > 0;
+
+ if (hasMetadata) {
+ deprecated(
+ 'updateOrganization(organizationId, { publicMetadata | privateMetadata })',
+ 'Use updateOrganizationMetadata for partial updates (merge) or replaceOrganizationMetadata for full replacement.',
+ );
+ }
+
+ if (!hasMetadata) {
+ return this.request<Organization>({
+ method: 'PATCH',
+ path: joinPaths(basePath, organizationId),
+ bodyParams: rest,
+ });
+ }
+
+ if (hasRest) {
+ await this.request<Organization>({
+ method: 'PATCH',
+ path: joinPaths(basePath, organizationId),
+ bodyParams: rest,
+ });
+ }
+
  return this.request<Organization>({
- method: 'PATCH',
- path: joinPaths(basePath, organizationId),
- bodyParams: params,
+ method: 'PUT',
+ path: joinPaths(basePath, organizationId, 'metadata'),
+ bodyParams: { publicMetadata, privateMetadata },
  });
  }
 
@@ -298,6 +345,21 @@ export class OrganizationAPI extends AbstractAPI {
  });
  }
 
+ /**
+ * Replace an organization's metadata. Supplied fields are overwritten in full;
+ * fields omitted from `params` are left unchanged. Prefer
+ * `updateOrganizationMetadata` for partial updates with deep-merge semantics.
+ */
+ public async replaceOrganizationMetadata(organizationId: string, params: MetadataParams) {
+ this.requireId(organizationId);
+
+ return this.request<Organization>({
+ method: 'PUT',
+ path: joinPaths(basePath, organizationId, 'metadata'),
+ bodyParams: params,
+ });
+ }
+
  public async deleteOrganization(organizationId: string) {
  return this.request<Organization>({
  method: 'DELETE',

packages/backend/src/constants.ts

@@ -3,7 +3,7 @@ export const API_VERSION = 'v1';
 
 export const USER_AGENT = `${PACKAGE_NAME}@${PACKAGE_VERSION}`;
 export const MAX_CACHE_LAST_UPDATED_AT_SECONDS = 5 * 60;
-export const SUPPORTED_BAPI_VERSION = '2025-11-10';
+export const SUPPORTED_BAPI_VERSION = '2026-05-12';
 
 const Attributes = {
  AuthToken: '__clerkAuthToken',

packages/backend/src/tokens/__tests__/handshake.test.ts

@@ -447,7 +447,7 @@ describe('HandshakeService', () => {
 
  // Verify all required parameters are present
  expect(url.searchParams.get('redirect_url')).toBeDefined();
- expect(url.searchParams.get('__clerk_api_version')).toBe('2025-11-10');
+ expect(url.searchParams.get('__clerk_api_version')).toBe('2026-05-12');
  expect(url.searchParams.get(constants.QueryParameters.SuffixedCookies)).toMatch(/^(true|false)$/);
  expect(url.searchParams.get(constants.QueryParameters.HandshakeReason)).toBe('test-reason');
  });

packages/shared/src/internal/clerk-js/constants.ts

@@ -62,7 +62,7 @@ export const SIGN_UP_MODES = {
 } satisfies Record<string, SignUpModes>;
 
 // This is the currently supported version of the Frontend API
-export const SUPPORTED_FAPI_VERSION = '2025-11-10';
+export const SUPPORTED_FAPI_VERSION = '2026-05-12';
 
 export const CAPTCHA_ELEMENT_ID = 'clerk-captcha';
 export const CAPTCHA_INVISIBLE_CLASSNAME = 'clerk-invisible-captcha';

.changeset/deprecate-update-organization-metadata.md

@@ -0,0 +1,23 @@
+---
+'@clerk/backend': minor
+---
+
+Add `clerkClient.organizations.replaceOrganizationMetadata(organizationId, params)` for replacing an organization's metadata fields in full.
+
+Use `replaceOrganizationMetadata` when the provided metadata should become the complete value for that metadata field:
+
+```ts
+await clerkClient.organizations.replaceOrganizationMetadata(organizationId, {
+ publicMetadata: { plan: 'pro' },
+});
+```
+
+Use `clerkClient.organizations.updateOrganizationMetadata(organizationId, params)` when you want to partially update metadata with deep-merge semantics:
+
+```ts
+await clerkClient.organizations.updateOrganizationMetadata(organizationId, {
+ publicMetadata: { onboardingComplete: true },
+});
+```
+
+The `publicMetadata` and `privateMetadata` parameters on `clerkClient.organizations.updateOrganization()` are now deprecated. They continue to work, but new code should use `updateOrganizationMetadata()` for partial updates or `replaceOrganizationMetadata()` for full replacement.

packages/backend/src/api/__tests__/OrganizationApi.test.ts

@@ -1,5 +1,5 @@
 import { http, HttpResponse } from 'msw';
-import { describe, expect, expectTypeOf, it } from 'vitest';
+import { describe, expect, expectTypeOf, it, vi } from 'vitest';
 
 import { server, validateHeaders } from '../../mock-server';
 import { createBackendApiClient } from '../factory';
@@ -14,29 +14,199 @@ describe('OrganizationAPI', () => {
 
  const organizationId = 'org_123';
 
- const mockInvitation = {
- object: 'organization_invitation',
- id: 'orginv_1',
- email_address: 'one@example.com',
- role: 'org:member',
- role_name: 'Member',
- organization_id: organizationId,
- status: 'pending',
+ const mockOrgResponse = {
+ object: 'organization',
+ id: organizationId,
+ name: 'Test Org',
+ slug: 'test-org',
  public_metadata: {},
  private_metadata: {},
- url: null,
- created_at: 1640995200,
- updated_at: 1640995200,
- expires_at: 1643673600,
  };
 
+ describe('updateOrganization', () => {
+ it('calls PATCH /organizations/{id} when no metadata fields are provided', async () => {
+ const patchHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = await request.json();
+ expect(body).toEqual({ name: 'New Name' });
+ return HttpResponse.json(mockOrgResponse);
+ });
+
+ server.use(
+ http.patch(`https://api.clerk.test/v1/organizations/${organizationId}`, validateHeaders(patchHandler)),
+ );
+
+ const response = await apiClient.organizations.updateOrganization(organizationId, { name: 'New Name' });
+
+ expect(patchHandler).toHaveBeenCalledTimes(1);
+ expect(response.id).toBe(organizationId);
+ });
+
+ it('routes metadata to PUT /organizations/{id}/metadata when only metadata is provided', async () => {
+ const patchHandler = vi.fn(() => HttpResponse.json(mockOrgResponse));
+ const putHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ public_metadata: { foo: 'bar' },
+ });
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ public_metadata: { foo: 'bar' },
+ });
+ });
+
+ server.use(
+ http.patch(`https://api.clerk.test/v1/organizations/${organizationId}`, validateHeaders(patchHandler)),
+ http.put(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(putHandler)),
+ );
+
+ const response = await apiClient.organizations.updateOrganization(organizationId, {
+ publicMetadata: { foo: 'bar' },
+ });
+
+ expect(patchHandler).not.toHaveBeenCalled();
+ expect(putHandler).toHaveBeenCalledTimes(1);
+ expect(response.publicMetadata).toEqual({ foo: 'bar' });
+ });
+
+ it('splits mixed calls: PATCH for non-metadata, then PUT for metadata', async () => {
+ const calls: string[] = [];
+
+ const patchHandler = vi.fn(async ({ request }: { request: Request }) => {
+ calls.push('patch');
+ const body = await request.json();
+ expect(body).toEqual({ name: 'New Name' });
+ return HttpResponse.json(mockOrgResponse);
+ });
+
+ const putHandler = vi.fn(async ({ request }: { request: Request }) => {
+ calls.push('put');
+ const body = await request.json();
+ expect(body).toEqual({
+ public_metadata: { plan: 'pro' },
+ private_metadata: { invoice: 'inv_1' },
+ });
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ name: 'New Name',
+ public_metadata: { plan: 'pro' },
+ private_metadata: { invoice: 'inv_1' },
+ });
+ });
+
+ server.use(
+ http.patch(`https://api.clerk.test/v1/organizations/${organizationId}`, validateHeaders(patchHandler)),
+ http.put(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(putHandler)),
+ );
+
+ const response = await apiClient.organizations.updateOrganization(organizationId, {
+ name: 'New Name',
+ publicMetadata: { plan: 'pro' },
+ privateMetadata: { invoice: 'inv_1' },
+ });
+
+ expect(patchHandler).toHaveBeenCalledTimes(1);
+ expect(putHandler).toHaveBeenCalledTimes(1);
+ expect(calls).toEqual(['patch', 'put']);
+ expect(response.name).toBe('New Name');
+ expect(response.publicMetadata).toEqual({ plan: 'pro' });
+ });
+
+ it('passes only metadata fields that were explicitly provided to PUT', async () => {
+ const putHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = (await request.json()) as Record<string, unknown>;
+ expect(body.private_metadata).toEqual({ secret: 'value' });
+ expect(body).not.toHaveProperty('public_metadata');
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ private_metadata: { secret: 'value' },
+ });
+ });
+
+ server.use(
+ http.put(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(putHandler)),
+ );
+
+ await apiClient.organizations.updateOrganization(organizationId, {
+ privateMetadata: { secret: 'value' },
+ });
+
+ expect(putHandler).toHaveBeenCalledTimes(1);
+ });
+ });
+
+ describe('updateOrganizationMetadata', () => {
+ it('still hits PATCH /organizations/{id}/metadata (unchanged)', async () => {
+ const patchHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ public_metadata: { merge: true },
+ });
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ public_metadata: { merge: true },
+ });
+ });
+
+ server.use(
+ http.patch(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(patchHandler)),
+ );
+
+ await apiClient.organizations.updateOrganizationMetadata(organizationId, {
+ publicMetadata: { merge: true },
+ });
+
+ expect(patchHandler).toHaveBeenCalledTimes(1);
+ });
+ });
+
+ describe('replaceOrganizationMetadata', () => {
+ it('hits PUT /organizations/{id}/metadata', async () => {
+ const putHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ public_metadata: { replaced: true },
+ });
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ public_metadata: { replaced: true },
+ });
+ });
+
+ server.use(
+ http.put(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(putHandler)),
+ );
+
+ const response = await apiClient.organizations.replaceOrganizationMetadata(organizationId, {
+ publicMetadata: { replaced: true },
+ });
+
+ expect(putHandler).toHaveBeenCalledTimes(1);
+ expect(response.publicMetadata).toEqual({ replaced: true });
+ });
+ });
+
  describe('createOrganizationInvitationBulk', () => {
+ const mockInvitation = {
+ object: 'organization_invitation',
+ id: 'orginv_1',
+ email_address: 'one@example.com',
+ role: 'org:member',
+ role_name: 'Member',
+ organization_id: organizationId,
+ status: 'pending',
+ public_metadata: {},
+ private_metadata: {},
+ url: null,
+ created_at: 1640995200,
+ updated_at: 1640995200,
+ expires_at: 1643673600,
+ };
+
  it('returns a paginated { data, totalCount } response matching the Backend API shape', async () => {
  server.use(
  http.post(
  `https://api.clerk.test/v1/organizations/${organizationId}/invitations/bulk`,
  validateHeaders(async ({ request }) => {
- // The SDK should forward the invitations as a snake_cased array body.
  const body = (await request.json()) as Array<Record<string, unknown>>;
  expect(body).toHaveLength(2);
  expect(body[0]).toMatchObject({
@@ -58,15 +228,11 @@ describe('OrganizationAPI', () => {
  { emailAddress: 'two@example.com', role: 'org:member', inviterUserId: 'user_1' },
  ]);
 
- // The Backend API wraps bulk results in a paginated envelope, and the
- // deserializer surfaces it as `{ data, totalCount }`.
  expect(response.data).toHaveLength(2);
  expect(response.data[0].emailAddress).toBe('one@example.com');
  expect(response.data[0].organizationId).toBe(organizationId);
  expect(response.totalCount).toBe(2);
 
- // The declared return type must reflect that paginated shape, the same
- // way the sibling `getOrganizationInvitationList` does.
  expectTypeOf(response).toEqualTypeOf<PaginatedResourceResponse<OrganizationInvitation[]>>();
  });
  });

packages/backend/src/api/endpoints/OrganizationApi.ts

@@ -2,6 +2,7 @@ import type { ClerkPaginationRequest, OrganizationEnrollmentMode } from '@clerk/
 
 import { runtime } from '../../runtime';
 import { joinPaths } from '../../util/path';
+import { deprecated } from '../../util/shared';
 import type {
  Organization,
  OrganizationDomain,
@@ -45,7 +46,25 @@ type UpdateParams = {
  slug?: string;
  adminDeleteEnabled?: boolean;
  maxAllowedMemberships?: number;
-} & MetadataParams;
+
+ /**
+ * Metadata visible to your Frontend and Backend APIs.
+ *
+ * @deprecated Updating metadata via `updateOrganization` is deprecated. Use
+ * `updateOrganizationMetadata` for partial updates (deep merge) or
+ * `replaceOrganizationMetadata` for full replacement.
+ */
+ publicMetadata?: OrganizationPublicMetadata;
+
+ /**
+ * Metadata visible only to your Backend API.
+ *
+ * @deprecated Updating metadata via `updateOrganization` is deprecated. Use
+ * `updateOrganizationMetadata` for partial updates (deep merge) or
+ * `replaceOrganizationMetadata` for full replacement.
+ */
+ privateMetadata?: OrganizationPrivateMetadata;
+};
 
 type UpdateLogoParams = {
  file: Blob | File;
@@ -256,10 +275,38 @@ export class OrganizationAPI extends AbstractAPI {
 
  public async updateOrganization(organizationId: string, params: UpdateParams) {
  this.requireId(organizationId);
+
+ const { publicMetadata, privateMetadata, ...rest } = params;
+ const hasMetadata = publicMetadata !== undefined || privateMetadata !== undefined;
+ const hasRest = Object.keys(rest).length > 0;
+
+ if (hasMetadata) {
+ deprecated(
+ 'updateOrganization(organizationId, { publicMetadata | privateMetadata })',
+ 'Use updateOrganizationMetadata for partial updates (merge) or replaceOrganizationMetadata for full replacement.',
+ );
+ }
+
+ if (!hasMetadata) {
+ return this.request<Organization>({
+ method: 'PATCH',
+ path: joinPaths(basePath, organizationId),
+ bodyParams: rest,
+ });
+ }
+
+ if (hasRest) {
+ await this.request<Organization>({
+ method: 'PATCH',
+ path: joinPaths(basePath, organizationId),
+ bodyParams: rest,
+ });
+ }
+
  return this.request<Organization>({
- method: 'PATCH',
- path: joinPaths(basePath, organizationId),
- bodyParams: params,
+ method: 'PUT',
+ path: joinPaths(basePath, organizationId, 'metadata'),
+ bodyParams: { publicMetadata, privateMetadata },
  });
  }
 
@@ -298,6 +345,21 @@ export class OrganizationAPI extends AbstractAPI {
  });
  }
 
+ /**
+ * Replace an organization's metadata. Supplied fields are overwritten in full;
+ * fields omitted from `params` are left unchanged. Prefer
+ * `updateOrganizationMetadata` for partial updates with deep-merge semantics.
+ */
+ public async replaceOrganizationMetadata(organizationId: string, params: MetadataParams) {
+ this.requireId(organizationId);
+
+ return this.request<Organization>({
+ method: 'PUT',
+ path: joinPaths(basePath, organizationId, 'metadata'),
+ bodyParams: params,
+ });
+ }
+
  public async deleteOrganization(organizationId: string) {
  return this.request<Organization>({
  method: 'DELETE',

packages/backend/src/constants.ts

@@ -3,7 +3,7 @@ export const API_VERSION = 'v1';
 
 export const USER_AGENT = `${PACKAGE_NAME}@${PACKAGE_VERSION}`;
 export const MAX_CACHE_LAST_UPDATED_AT_SECONDS = 5 * 60;
-export const SUPPORTED_BAPI_VERSION = '2025-11-10';
+export const SUPPORTED_BAPI_VERSION = '2026-05-12';
 
 const Attributes = {
  AuthToken: '__clerkAuthToken',

packages/backend/src/tokens/__tests__/handshake.test.ts

@@ -447,7 +447,7 @@ describe('HandshakeService', () => {
 
  // Verify all required parameters are present
  expect(url.searchParams.get('redirect_url')).toBeDefined();
- expect(url.searchParams.get('__clerk_api_version')).toBe('2025-11-10');
+ expect(url.searchParams.get('__clerk_api_version')).toBe('2026-05-12');
  expect(url.searchParams.get(constants.QueryParameters.SuffixedCookies)).toMatch(/^(true|false)$/);
  expect(url.searchParams.get(constants.QueryParameters.HandshakeReason)).toBe('test-reason');
  });

packages/shared/src/internal/clerk-js/constants.ts

@@ -62,7 +62,7 @@ export const SIGN_UP_MODES = {
 } satisfies Record<string, SignUpModes>;
 
 // This is the currently supported version of the Frontend API
-export const SUPPORTED_FAPI_VERSION = '2025-11-10';
+export const SUPPORTED_FAPI_VERSION = '2026-05-12';
 
 export const CAPTCHA_ELEMENT_ID = 'clerk-captcha';
 export const CAPTCHA_INVISIBLE_CLASSNAME = 'clerk-invisible-captcha';

.changeset/deprecate-update-organization-metadata.md

@@ -0,0 +1,23 @@
+---
+'@clerk/backend': minor
+---
+
+Add `clerkClient.organizations.replaceOrganizationMetadata(organizationId, params)` for replacing an organization's metadata fields in full.
+
+Use `replaceOrganizationMetadata` when the provided metadata should become the complete value for that metadata field:
+
+```ts
+await clerkClient.organizations.replaceOrganizationMetadata(organizationId, {
+ publicMetadata: { plan: 'pro' },
+});
+```
+
+Use `clerkClient.organizations.updateOrganizationMetadata(organizationId, params)` when you want to partially update metadata with deep-merge semantics:
+
+```ts
+await clerkClient.organizations.updateOrganizationMetadata(organizationId, {
+ publicMetadata: { onboardingComplete: true },
+});
+```
+
+The `publicMetadata` and `privateMetadata` parameters on `clerkClient.organizations.updateOrganization()` are now deprecated. They continue to work, but new code should use `updateOrganizationMetadata()` for partial updates or `replaceOrganizationMetadata()` for full replacement.

packages/backend/src/api/__tests__/OrganizationApi.test.ts

@@ -1,5 +1,5 @@
 import { http, HttpResponse } from 'msw';
-import { describe, expect, expectTypeOf, it } from 'vitest';
+import { describe, expect, expectTypeOf, it, vi } from 'vitest';
 
 import { server, validateHeaders } from '../../mock-server';
 import { createBackendApiClient } from '../factory';
@@ -14,29 +14,199 @@ describe('OrganizationAPI', () => {
 
  const organizationId = 'org_123';
 
- const mockInvitation = {
- object: 'organization_invitation',
- id: 'orginv_1',
- email_address: 'one@example.com',
- role: 'org:member',
- role_name: 'Member',
- organization_id: organizationId,
- status: 'pending',
+ const mockOrgResponse = {
+ object: 'organization',
+ id: organizationId,
+ name: 'Test Org',
+ slug: 'test-org',
  public_metadata: {},
  private_metadata: {},
- url: null,
- created_at: 1640995200,
- updated_at: 1640995200,
- expires_at: 1643673600,
  };
 
+ describe('updateOrganization', () => {
+ it('calls PATCH /organizations/{id} when no metadata fields are provided', async () => {
+ const patchHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = await request.json();
+ expect(body).toEqual({ name: 'New Name' });
+ return HttpResponse.json(mockOrgResponse);
+ });
+
+ server.use(
+ http.patch(`https://api.clerk.test/v1/organizations/${organizationId}`, validateHeaders(patchHandler)),
+ );
+
+ const response = await apiClient.organizations.updateOrganization(organizationId, { name: 'New Name' });
+
+ expect(patchHandler).toHaveBeenCalledTimes(1);
+ expect(response.id).toBe(organizationId);
+ });
+
+ it('routes metadata to PUT /organizations/{id}/metadata when only metadata is provided', async () => {
+ const patchHandler = vi.fn(() => HttpResponse.json(mockOrgResponse));
+ const putHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ public_metadata: { foo: 'bar' },
+ });
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ public_metadata: { foo: 'bar' },
+ });
+ });
+
+ server.use(
+ http.patch(`https://api.clerk.test/v1/organizations/${organizationId}`, validateHeaders(patchHandler)),
+ http.put(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(putHandler)),
+ );
+
+ const response = await apiClient.organizations.updateOrganization(organizationId, {
+ publicMetadata: { foo: 'bar' },
+ });
+
+ expect(patchHandler).not.toHaveBeenCalled();
+ expect(putHandler).toHaveBeenCalledTimes(1);
+ expect(response.publicMetadata).toEqual({ foo: 'bar' });
+ });
+
+ it('splits mixed calls: PATCH for non-metadata, then PUT for metadata', async () => {
+ const calls: string[] = [];
+
+ const patchHandler = vi.fn(async ({ request }: { request: Request }) => {
+ calls.push('patch');
+ const body = await request.json();
+ expect(body).toEqual({ name: 'New Name' });
+ return HttpResponse.json(mockOrgResponse);
+ });
+
+ const putHandler = vi.fn(async ({ request }: { request: Request }) => {
+ calls.push('put');
+ const body = await request.json();
+ expect(body).toEqual({
+ public_metadata: { plan: 'pro' },
+ private_metadata: { invoice: 'inv_1' },
+ });
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ name: 'New Name',
+ public_metadata: { plan: 'pro' },
+ private_metadata: { invoice: 'inv_1' },
+ });
+ });
+
+ server.use(
+ http.patch(`https://api.clerk.test/v1/organizations/${organizationId}`, validateHeaders(patchHandler)),
+ http.put(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(putHandler)),
+ );
+
+ const response = await apiClient.organizations.updateOrganization(organizationId, {
+ name: 'New Name',
+ publicMetadata: { plan: 'pro' },
+ privateMetadata: { invoice: 'inv_1' },
+ });
+
+ expect(patchHandler).toHaveBeenCalledTimes(1);
+ expect(putHandler).toHaveBeenCalledTimes(1);
+ expect(calls).toEqual(['patch', 'put']);
+ expect(response.name).toBe('New Name');
+ expect(response.publicMetadata).toEqual({ plan: 'pro' });
+ });
+
+ it('passes only metadata fields that were explicitly provided to PUT', async () => {
+ const putHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = (await request.json()) as Record<string, unknown>;
+ expect(body.private_metadata).toEqual({ secret: 'value' });
+ expect(body).not.toHaveProperty('public_metadata');
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ private_metadata: { secret: 'value' },
+ });
+ });
+
+ server.use(
+ http.put(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(putHandler)),
+ );
+
+ await apiClient.organizations.updateOrganization(organizationId, {
+ privateMetadata: { secret: 'value' },
+ });
+
+ expect(putHandler).toHaveBeenCalledTimes(1);
+ });
+ });
+
+ describe('updateOrganizationMetadata', () => {
+ it('still hits PATCH /organizations/{id}/metadata (unchanged)', async () => {
+ const patchHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ public_metadata: { merge: true },
+ });
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ public_metadata: { merge: true },
+ });
+ });
+
+ server.use(
+ http.patch(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(patchHandler)),
+ );
+
+ await apiClient.organizations.updateOrganizationMetadata(organizationId, {
+ publicMetadata: { merge: true },
+ });
+
+ expect(patchHandler).toHaveBeenCalledTimes(1);
+ });
+ });
+
+ describe('replaceOrganizationMetadata', () => {
+ it('hits PUT /organizations/{id}/metadata', async () => {
+ const putHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ public_metadata: { replaced: true },
+ });
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ public_metadata: { replaced: true },
+ });
+ });
+
+ server.use(
+ http.put(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(putHandler)),
+ );
+
+ const response = await apiClient.organizations.replaceOrganizationMetadata(organizationId, {
+ publicMetadata: { replaced: true },
+ });
+
+ expect(putHandler).toHaveBeenCalledTimes(1);
+ expect(response.publicMetadata).toEqual({ replaced: true });
+ });
+ });
+
  describe('createOrganizationInvitationBulk', () => {
+ const mockInvitation = {
+ object: 'organization_invitation',
+ id: 'orginv_1',
+ email_address: 'one@example.com',
+ role: 'org:member',
+ role_name: 'Member',
+ organization_id: organizationId,
+ status: 'pending',
+ public_metadata: {},
+ private_metadata: {},
+ url: null,
+ created_at: 1640995200,
+ updated_at: 1640995200,
+ expires_at: 1643673600,
+ };
+
  it('returns a paginated { data, totalCount } response matching the Backend API shape', async () => {
  server.use(
  http.post(
  `https://api.clerk.test/v1/organizations/${organizationId}/invitations/bulk`,
  validateHeaders(async ({ request }) => {
- // The SDK should forward the invitations as a snake_cased array body.
  const body = (await request.json()) as Array<Record<string, unknown>>;
  expect(body).toHaveLength(2);
  expect(body[0]).toMatchObject({
@@ -58,15 +228,11 @@ describe('OrganizationAPI', () => {
  { emailAddress: 'two@example.com', role: 'org:member', inviterUserId: 'user_1' },
  ]);
 
- // The Backend API wraps bulk results in a paginated envelope, and the
- // deserializer surfaces it as `{ data, totalCount }`.
  expect(response.data).toHaveLength(2);
  expect(response.data[0].emailAddress).toBe('one@example.com');
  expect(response.data[0].organizationId).toBe(organizationId);
  expect(response.totalCount).toBe(2);
 
- // The declared return type must reflect that paginated shape, the same
- // way the sibling `getOrganizationInvitationList` does.
  expectTypeOf(response).toEqualTypeOf<PaginatedResourceResponse<OrganizationInvitation[]>>();
  });
  });

packages/backend/src/api/endpoints/OrganizationApi.ts

@@ -2,6 +2,7 @@ import type { ClerkPaginationRequest, OrganizationEnrollmentMode } from '@clerk/
 
 import { runtime } from '../../runtime';
 import { joinPaths } from '../../util/path';
+import { deprecated } from '../../util/shared';
 import type {
  Organization,
  OrganizationDomain,
@@ -45,7 +46,25 @@ type UpdateParams = {
  slug?: string;
  adminDeleteEnabled?: boolean;
  maxAllowedMemberships?: number;
-} & MetadataParams;
+
+ /**
+ * Metadata visible to your Frontend and Backend APIs.
+ *
+ * @deprecated Updating metadata via `updateOrganization` is deprecated. Use
+ * `updateOrganizationMetadata` for partial updates (deep merge) or
+ * `replaceOrganizationMetadata` for full replacement.
+ */
+ publicMetadata?: OrganizationPublicMetadata;
+
+ /**
+ * Metadata visible only to your Backend API.
+ *
+ * @deprecated Updating metadata via `updateOrganization` is deprecated. Use
+ * `updateOrganizationMetadata` for partial updates (deep merge) or
+ * `replaceOrganizationMetadata` for full replacement.
+ */
+ privateMetadata?: OrganizationPrivateMetadata;
+};
 
 type UpdateLogoParams = {
  file: Blob | File;
@@ -256,10 +275,38 @@ export class OrganizationAPI extends AbstractAPI {
 
  public async updateOrganization(organizationId: string, params: UpdateParams) {
  this.requireId(organizationId);
+
+ const { publicMetadata, privateMetadata, ...rest } = params;
+ const hasMetadata = publicMetadata !== undefined || privateMetadata !== undefined;
+ const hasRest = Object.keys(rest).length > 0;
+
+ if (hasMetadata) {
+ deprecated(
+ 'updateOrganization(organizationId, { publicMetadata | privateMetadata })',
+ 'Use updateOrganizationMetadata for partial updates (merge) or replaceOrganizationMetadata for full replacement.',
+ );
+ }
+
+ if (!hasMetadata) {
+ return this.request<Organization>({
+ method: 'PATCH',
+ path: joinPaths(basePath, organizationId),
+ bodyParams: rest,
+ });
+ }
+
+ if (hasRest) {
+ await this.request<Organization>({
+ method: 'PATCH',
+ path: joinPaths(basePath, organizationId),
+ bodyParams: rest,
+ });
+ }
+
  return this.request<Organization>({
- method: 'PATCH',
- path: joinPaths(basePath, organizationId),
- bodyParams: params,
+ method: 'PUT',
+ path: joinPaths(basePath, organizationId, 'metadata'),
+ bodyParams: { publicMetadata, privateMetadata },
  });
  }
 
@@ -298,6 +345,21 @@ export class OrganizationAPI extends AbstractAPI {
  });
  }
 
+ /**
+ * Replace an organization's metadata. Supplied fields are overwritten in full;
+ * fields omitted from `params` are left unchanged. Prefer
+ * `updateOrganizationMetadata` for partial updates with deep-merge semantics.
+ */
+ public async replaceOrganizationMetadata(organizationId: string, params: MetadataParams) {
+ this.requireId(organizationId);
+
+ return this.request<Organization>({
+ method: 'PUT',
+ path: joinPaths(basePath, organizationId, 'metadata'),
+ bodyParams: params,
+ });
+ }
+
  public async deleteOrganization(organizationId: string) {
  return this.request<Organization>({
  method: 'DELETE',

packages/backend/src/constants.ts

@@ -3,7 +3,7 @@ export const API_VERSION = 'v1';
 
 export const USER_AGENT = `${PACKAGE_NAME}@${PACKAGE_VERSION}`;
 export const MAX_CACHE_LAST_UPDATED_AT_SECONDS = 5 * 60;
-export const SUPPORTED_BAPI_VERSION = '2025-11-10';
+export const SUPPORTED_BAPI_VERSION = '2026-05-12';
 
 const Attributes = {
  AuthToken: '__clerkAuthToken',

packages/backend/src/tokens/__tests__/handshake.test.ts

@@ -447,7 +447,7 @@ describe('HandshakeService', () => {
 
  // Verify all required parameters are present
  expect(url.searchParams.get('redirect_url')).toBeDefined();
- expect(url.searchParams.get('__clerk_api_version')).toBe('2025-11-10');
+ expect(url.searchParams.get('__clerk_api_version')).toBe('2026-05-12');
  expect(url.searchParams.get(constants.QueryParameters.SuffixedCookies)).toMatch(/^(true|false)$/);
  expect(url.searchParams.get(constants.QueryParameters.HandshakeReason)).toBe('test-reason');
  });

packages/shared/src/internal/clerk-js/constants.ts

@@ -62,7 +62,7 @@ export const SIGN_UP_MODES = {
 } satisfies Record<string, SignUpModes>;
 
 // This is the currently supported version of the Frontend API
-export const SUPPORTED_FAPI_VERSION = '2025-11-10';
+export const SUPPORTED_FAPI_VERSION = '2026-05-12';
 
 export const CAPTCHA_ELEMENT_ID = 'clerk-captcha';
 export const CAPTCHA_INVISIBLE_CLASSNAME = 'clerk-invisible-captcha';

.changeset/deprecate-update-organization-metadata.md

@@ -0,0 +1,23 @@
+---
+'@clerk/backend': minor
+---
+
+Add `clerkClient.organizations.replaceOrganizationMetadata(organizationId, params)` for replacing an organization's metadata fields in full.
+
+Use `replaceOrganizationMetadata` when the provided metadata should become the complete value for that metadata field:
+
+```ts
+await clerkClient.organizations.replaceOrganizationMetadata(organizationId, {
+ publicMetadata: { plan: 'pro' },
+});
+```
+
+Use `clerkClient.organizations.updateOrganizationMetadata(organizationId, params)` when you want to partially update metadata with deep-merge semantics:
+
+```ts
+await clerkClient.organizations.updateOrganizationMetadata(organizationId, {
+ publicMetadata: { onboardingComplete: true },
+});
+```
+
+The `publicMetadata` and `privateMetadata` parameters on `clerkClient.organizations.updateOrganization()` are now deprecated. They continue to work, but new code should use `updateOrganizationMetadata()` for partial updates or `replaceOrganizationMetadata()` for full replacement.

packages/backend/src/api/__tests__/OrganizationApi.test.ts

@@ -1,5 +1,5 @@
 import { http, HttpResponse } from 'msw';
-import { describe, expect, expectTypeOf, it } from 'vitest';
+import { describe, expect, expectTypeOf, it, vi } from 'vitest';
 
 import { server, validateHeaders } from '../../mock-server';
 import { createBackendApiClient } from '../factory';
@@ -14,29 +14,199 @@ describe('OrganizationAPI', () => {
 
  const organizationId = 'org_123';
 
- const mockInvitation = {
- object: 'organization_invitation',
- id: 'orginv_1',
- email_address: 'one@example.com',
- role: 'org:member',
- role_name: 'Member',
- organization_id: organizationId,
- status: 'pending',
+ const mockOrgResponse = {
+ object: 'organization',
+ id: organizationId,
+ name: 'Test Org',
+ slug: 'test-org',
  public_metadata: {},
  private_metadata: {},
- url: null,
- created_at: 1640995200,
- updated_at: 1640995200,
- expires_at: 1643673600,
  };
 
+ describe('updateOrganization', () => {
+ it('calls PATCH /organizations/{id} when no metadata fields are provided', async () => {
+ const patchHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = await request.json();
+ expect(body).toEqual({ name: 'New Name' });
+ return HttpResponse.json(mockOrgResponse);
+ });
+
+ server.use(
+ http.patch(`https://api.clerk.test/v1/organizations/${organizationId}`, validateHeaders(patchHandler)),
+ );
+
+ const response = await apiClient.organizations.updateOrganization(organizationId, { name: 'New Name' });
+
+ expect(patchHandler).toHaveBeenCalledTimes(1);
+ expect(response.id).toBe(organizationId);
+ });
+
+ it('routes metadata to PUT /organizations/{id}/metadata when only metadata is provided', async () => {
+ const patchHandler = vi.fn(() => HttpResponse.json(mockOrgResponse));
+ const putHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ public_metadata: { foo: 'bar' },
+ });
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ public_metadata: { foo: 'bar' },
+ });
+ });
+
+ server.use(
+ http.patch(`https://api.clerk.test/v1/organizations/${organizationId}`, validateHeaders(patchHandler)),
+ http.put(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(putHandler)),
+ );
+
+ const response = await apiClient.organizations.updateOrganization(organizationId, {
+ publicMetadata: { foo: 'bar' },
+ });
+
+ expect(patchHandler).not.toHaveBeenCalled();
+ expect(putHandler).toHaveBeenCalledTimes(1);
+ expect(response.publicMetadata).toEqual({ foo: 'bar' });
+ });
+
+ it('splits mixed calls: PATCH for non-metadata, then PUT for metadata', async () => {
+ const calls: string[] = [];
+
+ const patchHandler = vi.fn(async ({ request }: { request: Request }) => {
+ calls.push('patch');
+ const body = await request.json();
+ expect(body).toEqual({ name: 'New Name' });
+ return HttpResponse.json(mockOrgResponse);
+ });
+
+ const putHandler = vi.fn(async ({ request }: { request: Request }) => {
+ calls.push('put');
+ const body = await request.json();
+ expect(body).toEqual({
+ public_metadata: { plan: 'pro' },
+ private_metadata: { invoice: 'inv_1' },
+ });
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ name: 'New Name',
+ public_metadata: { plan: 'pro' },
+ private_metadata: { invoice: 'inv_1' },
+ });
+ });
+
+ server.use(
+ http.patch(`https://api.clerk.test/v1/organizations/${organizationId}`, validateHeaders(patchHandler)),
+ http.put(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(putHandler)),
+ );
+
+ const response = await apiClient.organizations.updateOrganization(organizationId, {
+ name: 'New Name',
+ publicMetadata: { plan: 'pro' },
+ privateMetadata: { invoice: 'inv_1' },
+ });
+
+ expect(patchHandler).toHaveBeenCalledTimes(1);
+ expect(putHandler).toHaveBeenCalledTimes(1);
+ expect(calls).toEqual(['patch', 'put']);
+ expect(response.name).toBe('New Name');
+ expect(response.publicMetadata).toEqual({ plan: 'pro' });
+ });
+
+ it('passes only metadata fields that were explicitly provided to PUT', async () => {
+ const putHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = (await request.json()) as Record<string, unknown>;
+ expect(body.private_metadata).toEqual({ secret: 'value' });
+ expect(body).not.toHaveProperty('public_metadata');
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ private_metadata: { secret: 'value' },
+ });
+ });
+
+ server.use(
+ http.put(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(putHandler)),
+ );
+
+ await apiClient.organizations.updateOrganization(organizationId, {
+ privateMetadata: { secret: 'value' },
+ });
+
+ expect(putHandler).toHaveBeenCalledTimes(1);
+ });
+ });
+
+ describe('updateOrganizationMetadata', () => {
+ it('still hits PATCH /organizations/{id}/metadata (unchanged)', async () => {
+ const patchHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ public_metadata: { merge: true },
+ });
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ public_metadata: { merge: true },
+ });
+ });
+
+ server.use(
+ http.patch(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(patchHandler)),
+ );
+
+ await apiClient.organizations.updateOrganizationMetadata(organizationId, {
+ publicMetadata: { merge: true },
+ });
+
+ expect(patchHandler).toHaveBeenCalledTimes(1);
+ });
+ });
+
+ describe('replaceOrganizationMetadata', () => {
+ it('hits PUT /organizations/{id}/metadata', async () => {
+ const putHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ public_metadata: { replaced: true },
+ });
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ public_metadata: { replaced: true },
+ });
+ });
+
+ server.use(
+ http.put(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(putHandler)),
+ );
+
+ const response = await apiClient.organizations.replaceOrganizationMetadata(organizationId, {
+ publicMetadata: { replaced: true },
+ });
+
+ expect(putHandler).toHaveBeenCalledTimes(1);
+ expect(response.publicMetadata).toEqual({ replaced: true });
+ });
+ });
+
  describe('createOrganizationInvitationBulk', () => {
+ const mockInvitation = {
+ object: 'organization_invitation',
+ id: 'orginv_1',
+ email_address: 'one@example.com',
+ role: 'org:member',
+ role_name: 'Member',
+ organization_id: organizationId,
+ status: 'pending',
+ public_metadata: {},
+ private_metadata: {},
+ url: null,
+ created_at: 1640995200,
+ updated_at: 1640995200,
+ expires_at: 1643673600,
+ };
+
  it('returns a paginated { data, totalCount } response matching the Backend API shape', async () => {
  server.use(
  http.post(
  `https://api.clerk.test/v1/organizations/${organizationId}/invitations/bulk`,
  validateHeaders(async ({ request }) => {
- // The SDK should forward the invitations as a snake_cased array body.
  const body = (await request.json()) as Array<Record<string, unknown>>;
  expect(body).toHaveLength(2);
  expect(body[0]).toMatchObject({
@@ -58,15 +228,11 @@ describe('OrganizationAPI', () => {
  { emailAddress: 'two@example.com', role: 'org:member', inviterUserId: 'user_1' },
  ]);
 
- // The Backend API wraps bulk results in a paginated envelope, and the
- // deserializer surfaces it as `{ data, totalCount }`.
  expect(response.data).toHaveLength(2);
  expect(response.data[0].emailAddress).toBe('one@example.com');
  expect(response.data[0].organizationId).toBe(organizationId);
  expect(response.totalCount).toBe(2);
 
- // The declared return type must reflect that paginated shape, the same
- // way the sibling `getOrganizationInvitationList` does.
  expectTypeOf(response).toEqualTypeOf<PaginatedResourceResponse<OrganizationInvitation[]>>();
  });
  });

packages/backend/src/api/endpoints/OrganizationApi.ts

@@ -2,6 +2,7 @@ import type { ClerkPaginationRequest, OrganizationEnrollmentMode } from '@clerk/
 
 import { runtime } from '../../runtime';
 import { joinPaths } from '../../util/path';
+import { deprecated } from '../../util/shared';
 import type {
  Organization,
  OrganizationDomain,
@@ -45,7 +46,25 @@ type UpdateParams = {
  slug?: string;
  adminDeleteEnabled?: boolean;
  maxAllowedMemberships?: number;
-} & MetadataParams;
+
+ /**
+ * Metadata visible to your Frontend and Backend APIs.
+ *
+ * @deprecated Updating metadata via `updateOrganization` is deprecated. Use
+ * `updateOrganizationMetadata` for partial updates (deep merge) or
+ * `replaceOrganizationMetadata` for full replacement.
+ */
+ publicMetadata?: OrganizationPublicMetadata;
+
+ /**
+ * Metadata visible only to your Backend API.
+ *
+ * @deprecated Updating metadata via `updateOrganization` is deprecated. Use
+ * `updateOrganizationMetadata` for partial updates (deep merge) or
+ * `replaceOrganizationMetadata` for full replacement.
+ */
+ privateMetadata?: OrganizationPrivateMetadata;
+};
 
 type UpdateLogoParams = {
  file: Blob | File;
@@ -256,10 +275,38 @@ export class OrganizationAPI extends AbstractAPI {
 
  public async updateOrganization(organizationId: string, params: UpdateParams) {
  this.requireId(organizationId);
+
+ const { publicMetadata, privateMetadata, ...rest } = params;
+ const hasMetadata = publicMetadata !== undefined || privateMetadata !== undefined;
+ const hasRest = Object.keys(rest).length > 0;
+
+ if (hasMetadata) {
+ deprecated(
+ 'updateOrganization(organizationId, { publicMetadata | privateMetadata })',
+ 'Use updateOrganizationMetadata for partial updates (merge) or replaceOrganizationMetadata for full replacement.',
+ );
+ }
+
+ if (!hasMetadata) {
+ return this.request<Organization>({
+ method: 'PATCH',
+ path: joinPaths(basePath, organizationId),
+ bodyParams: rest,
+ });
+ }
+
+ if (hasRest) {
+ await this.request<Organization>({
+ method: 'PATCH',
+ path: joinPaths(basePath, organizationId),
+ bodyParams: rest,
+ });
+ }
+
  return this.request<Organization>({
- method: 'PATCH',
- path: joinPaths(basePath, organizationId),
- bodyParams: params,
+ method: 'PUT',
+ path: joinPaths(basePath, organizationId, 'metadata'),
+ bodyParams: { publicMetadata, privateMetadata },
  });
  }
 
@@ -298,6 +345,21 @@ export class OrganizationAPI extends AbstractAPI {
  });
  }
 
+ /**
+ * Replace an organization's metadata. Supplied fields are overwritten in full;
+ * fields omitted from `params` are left unchanged. Prefer
+ * `updateOrganizationMetadata` for partial updates with deep-merge semantics.
+ */
+ public async replaceOrganizationMetadata(organizationId: string, params: MetadataParams) {
+ this.requireId(organizationId);
+
+ return this.request<Organization>({
+ method: 'PUT',
+ path: joinPaths(basePath, organizationId, 'metadata'),
+ bodyParams: params,
+ });
+ }
+
  public async deleteOrganization(organizationId: string) {
  return this.request<Organization>({
  method: 'DELETE',

packages/backend/src/constants.ts

@@ -3,7 +3,7 @@ export const API_VERSION = 'v1';
 
 export const USER_AGENT = `${PACKAGE_NAME}@${PACKAGE_VERSION}`;
 export const MAX_CACHE_LAST_UPDATED_AT_SECONDS = 5 * 60;
-export const SUPPORTED_BAPI_VERSION = '2025-11-10';
+export const SUPPORTED_BAPI_VERSION = '2026-05-12';
 
 const Attributes = {
  AuthToken: '__clerkAuthToken',

packages/backend/src/tokens/__tests__/handshake.test.ts

@@ -447,7 +447,7 @@ describe('HandshakeService', () => {
 
  // Verify all required parameters are present
  expect(url.searchParams.get('redirect_url')).toBeDefined();
- expect(url.searchParams.get('__clerk_api_version')).toBe('2025-11-10');
+ expect(url.searchParams.get('__clerk_api_version')).toBe('2026-05-12');
  expect(url.searchParams.get(constants.QueryParameters.SuffixedCookies)).toMatch(/^(true|false)$/);
  expect(url.searchParams.get(constants.QueryParameters.HandshakeReason)).toBe('test-reason');
  });

packages/shared/src/internal/clerk-js/constants.ts

@@ -62,7 +62,7 @@ export const SIGN_UP_MODES = {
 } satisfies Record<string, SignUpModes>;
 
 // This is the currently supported version of the Frontend API
-export const SUPPORTED_FAPI_VERSION = '2025-11-10';
+export const SUPPORTED_FAPI_VERSION = '2026-05-12';
 
 export const CAPTCHA_ELEMENT_ID = 'clerk-captcha';
 export const CAPTCHA_INVISIBLE_CLASSNAME = 'clerk-invisible-captcha';

.changeset/deprecate-update-organization-metadata.md

@@ -0,0 +1,23 @@
+---
+'@clerk/backend': minor
+---
+
+Add `clerkClient.organizations.replaceOrganizationMetadata(organizationId, params)` for replacing an organization's metadata fields in full.
+
+Use `replaceOrganizationMetadata` when the provided metadata should become the complete value for that metadata field:
+
+```ts
+await clerkClient.organizations.replaceOrganizationMetadata(organizationId, {
+ publicMetadata: { plan: 'pro' },
+});
+```
+
+Use `clerkClient.organizations.updateOrganizationMetadata(organizationId, params)` when you want to partially update metadata with deep-merge semantics:
+
+```ts
+await clerkClient.organizations.updateOrganizationMetadata(organizationId, {
+ publicMetadata: { onboardingComplete: true },
+});
+```
+
+The `publicMetadata` and `privateMetadata` parameters on `clerkClient.organizations.updateOrganization()` are now deprecated. They continue to work, but new code should use `updateOrganizationMetadata()` for partial updates or `replaceOrganizationMetadata()` for full replacement.

packages/backend/src/api/__tests__/OrganizationApi.test.ts

@@ -1,5 +1,5 @@
 import { http, HttpResponse } from 'msw';
-import { describe, expect, expectTypeOf, it } from 'vitest';
+import { describe, expect, expectTypeOf, it, vi } from 'vitest';
 
 import { server, validateHeaders } from '../../mock-server';
 import { createBackendApiClient } from '../factory';
@@ -14,29 +14,199 @@ describe('OrganizationAPI', () => {
 
  const organizationId = 'org_123';
 
- const mockInvitation = {
- object: 'organization_invitation',
- id: 'orginv_1',
- email_address: 'one@example.com',
- role: 'org:member',
- role_name: 'Member',
- organization_id: organizationId,
- status: 'pending',
+ const mockOrgResponse = {
+ object: 'organization',
+ id: organizationId,
+ name: 'Test Org',
+ slug: 'test-org',
  public_metadata: {},
  private_metadata: {},
- url: null,
- created_at: 1640995200,
- updated_at: 1640995200,
- expires_at: 1643673600,
  };
 
+ describe('updateOrganization', () => {
+ it('calls PATCH /organizations/{id} when no metadata fields are provided', async () => {
+ const patchHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = await request.json();
+ expect(body).toEqual({ name: 'New Name' });
+ return HttpResponse.json(mockOrgResponse);
+ });
+
+ server.use(
+ http.patch(`https://api.clerk.test/v1/organizations/${organizationId}`, validateHeaders(patchHandler)),
+ );
+
+ const response = await apiClient.organizations.updateOrganization(organizationId, { name: 'New Name' });
+
+ expect(patchHandler).toHaveBeenCalledTimes(1);
+ expect(response.id).toBe(organizationId);
+ });
+
+ it('routes metadata to PUT /organizations/{id}/metadata when only metadata is provided', async () => {
+ const patchHandler = vi.fn(() => HttpResponse.json(mockOrgResponse));
+ const putHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ public_metadata: { foo: 'bar' },
+ });
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ public_metadata: { foo: 'bar' },
+ });
+ });
+
+ server.use(
+ http.patch(`https://api.clerk.test/v1/organizations/${organizationId}`, validateHeaders(patchHandler)),
+ http.put(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(putHandler)),
+ );
+
+ const response = await apiClient.organizations.updateOrganization(organizationId, {
+ publicMetadata: { foo: 'bar' },
+ });
+
+ expect(patchHandler).not.toHaveBeenCalled();
+ expect(putHandler).toHaveBeenCalledTimes(1);
+ expect(response.publicMetadata).toEqual({ foo: 'bar' });
+ });
+
+ it('splits mixed calls: PATCH for non-metadata, then PUT for metadata', async () => {
+ const calls: string[] = [];
+
+ const patchHandler = vi.fn(async ({ request }: { request: Request }) => {
+ calls.push('patch');
+ const body = await request.json();
+ expect(body).toEqual({ name: 'New Name' });
+ return HttpResponse.json(mockOrgResponse);
+ });
+
+ const putHandler = vi.fn(async ({ request }: { request: Request }) => {
+ calls.push('put');
+ const body = await request.json();
+ expect(body).toEqual({
+ public_metadata: { plan: 'pro' },
+ private_metadata: { invoice: 'inv_1' },
+ });
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ name: 'New Name',
+ public_metadata: { plan: 'pro' },
+ private_metadata: { invoice: 'inv_1' },
+ });
+ });
+
+ server.use(
+ http.patch(`https://api.clerk.test/v1/organizations/${organizationId}`, validateHeaders(patchHandler)),
+ http.put(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(putHandler)),
+ );
+
+ const response = await apiClient.organizations.updateOrganization(organizationId, {
+ name: 'New Name',
+ publicMetadata: { plan: 'pro' },
+ privateMetadata: { invoice: 'inv_1' },
+ });
+
+ expect(patchHandler).toHaveBeenCalledTimes(1);
+ expect(putHandler).toHaveBeenCalledTimes(1);
+ expect(calls).toEqual(['patch', 'put']);
+ expect(response.name).toBe('New Name');
+ expect(response.publicMetadata).toEqual({ plan: 'pro' });
+ });
+
+ it('passes only metadata fields that were explicitly provided to PUT', async () => {
+ const putHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = (await request.json()) as Record<string, unknown>;
+ expect(body.private_metadata).toEqual({ secret: 'value' });
+ expect(body).not.toHaveProperty('public_metadata');
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ private_metadata: { secret: 'value' },
+ });
+ });
+
+ server.use(
+ http.put(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(putHandler)),
+ );
+
+ await apiClient.organizations.updateOrganization(organizationId, {
+ privateMetadata: { secret: 'value' },
+ });
+
+ expect(putHandler).toHaveBeenCalledTimes(1);
+ });
+ });
+
+ describe('updateOrganizationMetadata', () => {
+ it('still hits PATCH /organizations/{id}/metadata (unchanged)', async () => {
+ const patchHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ public_metadata: { merge: true },
+ });
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ public_metadata: { merge: true },
+ });
+ });
+
+ server.use(
+ http.patch(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(patchHandler)),
+ );
+
+ await apiClient.organizations.updateOrganizationMetadata(organizationId, {
+ publicMetadata: { merge: true },
+ });
+
+ expect(patchHandler).toHaveBeenCalledTimes(1);
+ });
+ });
+
+ describe('replaceOrganizationMetadata', () => {
+ it('hits PUT /organizations/{id}/metadata', async () => {
+ const putHandler = vi.fn(async ({ request }: { request: Request }) => {
+ const body = await request.json();
+ expect(body).toEqual({
+ public_metadata: { replaced: true },
+ });
+ return HttpResponse.json({
+ ...mockOrgResponse,
+ public_metadata: { replaced: true },
+ });
+ });
+
+ server.use(
+ http.put(`https://api.clerk.test/v1/organizations/${organizationId}/metadata`, validateHeaders(putHandler)),
+ );
+
+ const response = await apiClient.organizations.replaceOrganizationMetadata(organizationId, {
+ publicMetadata: { replaced: true },
+ });
+
+ expect(putHandler).toHaveBeenCalledTimes(1);
+ expect(response.publicMetadata).toEqual({ replaced: true });
+ });
+ });
+
  describe('createOrganizationInvitationBulk', () => {
+ const mockInvitation = {
+ object: 'organization_invitation',
+ id: 'orginv_1',
+ email_address: 'one@example.com',
+ role: 'org:member',
+ role_name: 'Member',
+ organization_id: organizationId,
+ status: 'pending',
+ public_metadata: {},
+ private_metadata: {},
+ url: null,
+ created_at: 1640995200,
+ updated_at: 1640995200,
+ expires_at: 1643673600,
+ };
+
  it('returns a paginated { data, totalCount } response matching the Backend API shape', async () => {
  server.use(
  http.post(
  `https://api.clerk.test/v1/organizations/${organizationId}/invitations/bulk`,
  validateHeaders(async ({ request }) => {
- // The SDK should forward the invitations as a snake_cased array body.
  const body = (await request.json()) as Array<Record<string, unknown>>;
  expect(body).toHaveLength(2);
  expect(body[0]).toMatchObject({
@@ -58,15 +228,11 @@ describe('OrganizationAPI', () => {
  { emailAddress: 'two@example.com', role: 'org:member', inviterUserId: 'user_1' },
  ]);
 
- // The Backend API wraps bulk results in a paginated envelope, and the
- // deserializer surfaces it as `{ data, totalCount }`.
  expect(response.data).toHaveLength(2);
  expect(response.data[0].emailAddress).toBe('one@example.com');
  expect(response.data[0].organizationId).toBe(organizationId);
  expect(response.totalCount).toBe(2);
 
- // The declared return type must reflect that paginated shape, the same
- // way the sibling `getOrganizationInvitationList` does.
  expectTypeOf(response).toEqualTypeOf<PaginatedResourceResponse<OrganizationInvitation[]>>();
  });
  });

packages/backend/src/api/endpoints/OrganizationApi.ts

@@ -2,6 +2,7 @@ import type { ClerkPaginationRequest, OrganizationEnrollmentMode } from '@clerk/
 
 import { runtime } from '../../runtime';
 import { joinPaths } from '../../util/path';
+import { deprecated } from '../../util/shared';
 import type {
  Organization,
  OrganizationDomain,
@@ -45,7 +46,25 @@ type UpdateParams = {
  slug?: string;
  adminDeleteEnabled?: boolean;
  maxAllowedMemberships?: number;
-} & MetadataParams;
+
+ /**
+ * Metadata visible to your Frontend and Backend APIs.
+ *
+ * @deprecated Updating metadata via `updateOrganization` is deprecated. Use
+ * `updateOrganizationMetadata` for partial updates (deep merge) or
+ * `replaceOrganizationMetadata` for full replacement.
+ */
+ publicMetadata?: OrganizationPublicMetadata;
+
+ /**
+ * Metadata visible only to your Backend API.
+ *
+ * @deprecated Updating metadata via `updateOrganization` is deprecated. Use
+ * `updateOrganizationMetadata` for partial updates (deep merge) or
+ * `replaceOrganizationMetadata` for full replacement.
+ */
+ privateMetadata?: OrganizationPrivateMetadata;
+};
 
 type UpdateLogoParams = {
  file: Blob | File;
@@ -256,10 +275,38 @@ export class OrganizationAPI extends AbstractAPI {
 
  public async updateOrganization(organizationId: string, params: UpdateParams) {
  this.requireId(organizationId);
+
+ const { publicMetadata, privateMetadata, ...rest } = params;
+ const hasMetadata = publicMetadata !== undefined || privateMetadata !== undefined;
+ const hasRest = Object.keys(rest).length > 0;
+
+ if (hasMetadata) {
+ deprecated(
+ 'updateOrganization(organizationId, { publicMetadata | privateMetadata })',
+ 'Use updateOrganizationMetadata for partial updates (merge) or replaceOrganizationMetadata for full replacement.',
+ );
+ }
+
+ if (!hasMetadata) {
+ return this.request<Organization>({
+ method: 'PATCH',
+ path: joinPaths(basePath, organizationId),
+ bodyParams: rest,
+ });
+ }
+
+ if (hasRest) {
+ await this.request<Organization>({
+ method: 'PATCH',
+ path: joinPaths(basePath, organizationId),
+ bodyParams: rest,
+ });
+ }
+
  return this.request<Organization>({
- method: 'PATCH',
- path: joinPaths(basePath, organizationId),
- bodyParams: params,
+ method: 'PUT',
+ path: joinPaths(basePath, organizationId, 'metadata'),
+ bodyParams: { publicMetadata, privateMetadata },
  });
  }
 
@@ -298,6 +345,21 @@ export class OrganizationAPI extends AbstractAPI {
  });
  }
 
+ /**
+ * Replace an organization's metadata. Supplied fields are overwritten in full;
+ * fields omitted from `params` are left unchanged. Prefer
+ * `updateOrganizationMetadata` for partial updates with deep-merge semantics.
+ */
+ public async replaceOrganizationMetadata(organizationId: string, params: MetadataParams) {
+ this.requireId(organizationId);
+
+ return this.request<Organization>({
+ method: 'PUT',
+ path: joinPaths(basePath, organizationId, 'metadata'),
+ bodyParams: params,
+ });
+ }
+
  public async deleteOrganization(organizationId: string) {
  return this.request<Organization>({
  method: 'DELETE',

packages/backend/src/constants.ts

@@ -3,7 +3,7 @@ export const API_VERSION = 'v1';
 
 export const USER_AGENT = `${PACKAGE_NAME}@${PACKAGE_VERSION}`;
 export const MAX_CACHE_LAST_UPDATED_AT_SECONDS = 5 * 60;
-export const SUPPORTED_BAPI_VERSION = '2025-11-10';
+export const SUPPORTED_BAPI_VERSION = '2026-05-12';
 
 const Attributes = {
  AuthToken: '__clerkAuthToken',

packages/backend/src/tokens/__tests__/handshake.test.ts

@@ -447,7 +447,7 @@ describe('HandshakeService', () => {
 
  // Verify all required parameters are present
  expect(url.searchParams.get('redirect_url')).toBeDefined();
- expect(url.searchParams.get('__clerk_api_version')).toBe('2025-11-10');
+ expect(url.searchParams.get('__clerk_api_version')).toBe('2026-05-12');
  expect(url.searchParams.get(constants.QueryParameters.SuffixedCookies)).toMatch(/^(true|false)$/);
  expect(url.searchParams.get(constants.QueryParameters.HandshakeReason)).toBe('test-reason');
  });

packages/shared/src/internal/clerk-js/constants.ts

@@ -62,7 +62,7 @@ export const SIGN_UP_MODES = {
 } satisfies Record<string, SignUpModes>;
 
 // This is the currently supported version of the Frontend API
-export const SUPPORTED_FAPI_VERSION = '2025-11-10';
+export const SUPPORTED_FAPI_VERSION = '2026-05-12';
 
 export const CAPTCHA_ELEMENT_ID = 'clerk-captcha';
 export const CAPTCHA_INVISIBLE_CLASSNAME = 'clerk-invisible-captcha';