---
title: "Replace a preference section"
method: PUT
path: "/preferences/sections/{section_id}"
tags: ["Preference Topics"]
---

# Replace a preference section

`PUT /preferences/sections/{section_id}`

Replace a workspace preference. Full document replacement; missing optional fields are cleared. Topics attached to the workspace preference are unaffected.

## Path parameters

- `section_id` string, required

## Request body

- WorkspacePreferenceReplaceRequest — Request body for replacing a workspace preference. Full document replacement; missing optional fields are cleared.
  - `name` string, required — Human-readable name for the workspace preference.
  - `description` string, nullable — Optional description shown under the section on the hosted preferences page. Omit to clear.
  - `routing_options` ChannelClassification[], nullable — Default channels for the workspace preference. Omit to clear.
  - `has_custom_routing` boolean, nullable — Whether the workspace preference defines custom routing for its topics.

## Response `200`

- WorkspacePreferenceGetResponse — A workspace preference in your workspace, including its topics.
  - `id` string, required — The workspace preference id.
  - `name` string, required — Human-readable name.
  - `description` string, nullable — Optional description shown under the section on the hosted preferences page.
  - `routing_options` ChannelClassification[], required — Default channels for the workspace preference. May be empty.
  - `has_custom_routing` boolean, required — Whether the workspace preference defines custom routing for its topics.
  - `created` string, required — ISO-8601 timestamp of when the workspace preference was created.
  - `creator` string, nullable — Id of the creator.
  - `updated` string, nullable — ISO-8601 timestamp of the last update.
  - `updater` string, nullable — Id of the last updater.
  - `topics` WorkspacePreferenceTopicGetResponse[], required — The topics contained in this workspace preference.
    - `id` string, required — The preference topic id.
    - `name` string, required — Human-readable name.
    - `description` string, nullable — Optional description shown under the topic on the hosted preferences page.
    - `default_status` 'OPTED_OUT' | 'OPTED_IN' | 'REQUIRED', required
    - `routing_options` ChannelClassification[], required — Default channels delivered for this topic. May be empty.
    - `allowed_preferences` AllowedPreference[], required — Preference controls a recipient may customize. May be empty.
    - `include_unsubscribe_header` boolean, required — Whether a list-unsubscribe header is included on emails for this topic.
    - `topic_data` object, required — Arbitrary metadata associated with the topic.
    - `created` string, required — ISO-8601 timestamp of when the topic was created.
    - `creator` string, nullable — Id of the creator.
    - `updated` string, required — ISO-8601 timestamp of the last update.
    - `updater` string, nullable — Id of the last updater.

## Other responses

- `400` — Bad Request
- `404` — Not Found

---

[API](https://skmtc.net/trycourier/apis/courier.md) · [All operations](https://skmtc.net/trycourier/apis/courier/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/trycourier/courier/versions/04f69fbf96a5/schema)