replaceOrganizationMetadata()

Replaces the metadata associated with the specified Organization. Unlike updateOrganizationMetadata(), which deep-merges into the existing metadata, this method uses replace semantics: when a metadata field is provided, its previous value is overwritten in full with no merging at any level.

The distinction is at two layers:

• Top-level field omission preserves the existing value. Each top-level field (publicMetadata, privateMetadata) is handled independently. If you don't include a field in the request, the stored value for that field is left untouched.
• The value inside a provided field is replaced in full. When you do include a field, its previous content is discarded — any nested keys present before but absent in the new value are dropped. There is no merge.

For the provided field, you can also send:

• {} (empty object) to clear the field.
• null to overwrite the field with a JSON null value. Prefer {} unless you specifically need a stored null.

Returns the updated Organization.

function replaceOrganizationMetadata(organizationId: string, params: { privateMetadata?: OrganizationPrivateMetadata; publicMetadata?: OrganizationPublicMetadata }): Promise<Organization>

Parameters

Usage

const organizationId = 'org_123'

const response = await clerkClient.organizations.replaceOrganizationMetadata(organizationId, {
  publicMetadata: {
    tier: 'enterprise',
  },
})

Backend API (BAPI) endpoint

This method in the SDK is a wrapper around the BAPI endpoint PUT/organizations/{organization_id}/metadata. See the BAPI reference⁠ for more information.

Here's an example of making a request directly to the endpoint using cURL.

curl -XPUT -H 'Authorization: Bearer YOUR_SECRET_KEY' -H "Content-type: application/json" -d '{
  "public_metadata": {
    "tier": "enterprise"
  }
}' 'https://api.clerk.com/v1/organizations/{organization_id}/metadata'