---
title: "Replace metadata for an organization"
method: PUT
path: "/organizations/{organization_id}/metadata"
tags: ["Organizations"]
---

# Replace metadata for an organization

`PUT /organizations/{organization_id}/metadata`

Replace an organization's metadata attributes with the provided values.
Unlike `PATCH /v1/organizations/{organization_id}/metadata` (merge semantics), this
endpoint replaces the supplied metadata fields entirely — the prior contents of each
supplied field are discarded. Fields omitted from the request body are left unchanged.
Prefer the `PATCH` endpoint for partial updates. Use `PUT` only when you explicitly
intend to overwrite a metadata field wholesale.

## Path parameters

- `organization_id` string, required

## Request body

- object
  - `public_metadata` object — Metadata saved on the organization, that is visible to both your frontend and backend. The existing value will be replaced entirely with the new object.
  - `private_metadata` object — Metadata saved on the organization that is only visible to your backend. The existing value will be replaced entirely with the new object.

## Response `200`

An organization

- Organization
  - `object` 'organization', required
  - `id` string, required
  - `name` string, required
  - `slug` string, required
  - `image_url` string
  - `has_image` boolean, required
  - `members_count` integer
  - `missing_member_with_elevated_permissions` boolean
  - `pending_invitations_count` integer
  - `max_allowed_memberships` integer, required
  - `admin_delete_enabled` boolean, required
  - `public_metadata` object, required
  - `private_metadata` object
  - `created_by` string
  - `created_at` integer, required — Unix timestamp of creation.
  - `updated_at` integer, required — Unix timestamp of last update.
  - `last_active_at` integer — Unix timestamp of last activity.
  - `role_set_key` string, nullable — The key of the [role set](https://clerk.com/docs/guides/organizations/control-access/role-sets) assigned to this organization.

## Other responses

- `400` — Request was not successful
- `401` — Authentication invalid
- `404` — Resource not found
- `422` — Invalid request parameters

---

[API](https://skmtc.net/clerk/apis/clerk-backend-api.md) · [All operations](https://skmtc.net/clerk/apis/clerk-backend-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/clerk/clerk-backend-api/revisions/cf036e7951d3/schema)