replaceUserMetadata()

Replaces the metadata associated with the specified user. Unlike updateUserMetadata(), 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, unsafeMetadata) 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 User.

function replaceUserMetadata(userId: string, params: { privateMetadata?: UserPrivateMetadata; publicMetadata?: UserPublicMetadata; unsafeMetadata?: UserUnsafeMetadata }): Promise<User>

Parameters

Usage

const userId = 'user_123'

const response = await clerkClient.users.replaceUserMetadata(userId, {
  publicMetadata: {
    role: 'admin',
  },
})

Backend API (BAPI) endpoint

This method in the SDK is a wrapper around the BAPI endpoint PUT/users/{user_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": {
    "role": "admin"
  }
}' 'https://api.clerk.com/v1/users/{user_id}/metadata'