---
title: Manage categories
slug: cms-saas/docs/manage-categories
docTags: 
createdAt: 2026-09-08T20:18:51.000Z
---

Taxonomy in Optimizely Content Management System (SaaS), also called CMS (SaaS), provides a structured system for organizing content. A taxonomy consists of terms that classify and categorize content. CMS (SaaS) supports hierarchical terms called categories. Categories form parent-child relationships with multiple nesting levels, which enables taxonomic organization, browsable navigation paths, and logical grouping of related content.

![Screenshot of the Categories page where parent and child categories display in a hierarchy](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/KejWbjQZx2ihe2fpkgrv1_categories.png)

## Category benefits

Categories provide the following benefits:

- **Structured organization** – Create multi-level hierarchies that reflect your content taxonomy, making it easier to organize large volumes of content according to business logic.
- **Enhanced discoverability** – Let users find content through category-based filtering, hierarchical navigation, and search in Content Manager.
- **Flexible classification** – Support both broad parent categories and specific leaf categories so you can classify content at the appropriate level of granularity.
- **Graph integration** – Optimizely Graph indexes category terms, which enables content queries in headless scenarios.
- **Scalability** – As your content library grows, categories provide consistent classification patterns that scale with your needs.

## When to use categories

Use categories in the following scenarios:

- **Content taxonomy** – Organize content according to a predefined taxonomy structure, such as Sport > Running > Training Plans.
- **Departmental structure** – Map organization structure to content ownership and reflect this structure in content classification.
- **Hierarchical navigation** – Provide users with browsable navigation paths through related content.
- **Multi-level classification** – Classify content at different granularity levels, with high-level categories and detailed subcategories.

## Create a category

1. Go to **Settings > Categories**.
2. Choose whether to create a standalone, parent, or child category:
   - **Standalone or parent category** – Click **Create** to add a top-level category with no parent.

     ![Screenshot of the Categories page where the Create button adds a top-level category](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/Ez8V4W84pzxBOSd0urFMS_parent-category.png)
   - **Child category** – Select **More > Create child** on an existing category to add a subcategory.

     ![Screenshot of the Categories page where the More menu shows the Create child option](https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/HbSaynUDj0N4UklvK9dVS_child-category.png)
3. Enter the following information:
   - **Display name** – A human-readable label that displays in the UI. Localizable. Required. Maximum 255 characters.
   - **Key** – A unique identifier for the category in APIs and code. Required. Maximum 100 characters.
   - **Description** – (Optional) An explanation of the purpose or usage of the category. Localizable. Maximum 500 characters.
   - **Parent** – Displays the parent category. CMS (SaaS) populates this field automatically based on where you start the create action. Read-only.
   - **Visible** – Controls whether the category displays in category selection UI.
   - **Selectable** – Controls whether CMS users can assign this category to content.
   - **Usage** – Metadata that indicates the intended scope of the category. Select **Public** for general use or **Internal** for internal classification. This metadata guides developers. Optimizely Graph indexes both **Public** and **Internal** categories and includes them in queries.

     :::hint{type="info"}
     **Note**

     You cannot create a **Public** category as a child of an **Internal** parent.
     :::
4. (Optional) Click **+** to continue creating categories at the same level (parent or child).
5. Click **Create**.

::Image[]{src="https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/rPXM6n5DLbcpGZQtEHT_Y_create-categories.png" alt="Screenshot of the create category form where the fields define a new category" size="100" isUploading="false" position="center" width="936" height="228" darkWidth="936" darkHeight="228" showCaption="false" indent="1"}

To assign categories to a content item, go to [Categorize content](docId\:ZUy-6r4zP3moOFKq3BmUY).

### Visible and Selectable flags

The **Visible** and **Selectable** flags control category behavior in different contexts:

- **Visible** – Determines whether the category displays in category selection windows and UI components.
- **Selectable** – Determines whether CMS users can assign the category directly to content items.

These flags apply to individual categories and do not cascade to child categories. Configure each category according to its purpose. The following patterns are common:

- **Active categories** – Select both **Visible** and **Selectable** for categories that users should see and assign.
- **Deprecated categories** – Clear both **Visible** and **Selectable** to hide a category without deleting it.
- **Historic categories** – Select **Visible** and clear **Selectable** to show a category in the UI without letting users assign it to content. Use this pattern for a category that remains visible for organizational purposes, such as a past marketing campaign.

### Usage field

The **Usage** field is metadata that indicates how you intend to use a category:

- **Public** – Categories intended for public-facing use cases, such as website navigation and public content organization.
- **Internal** – Categories intended for internal classification, such as workflow states, internal department codes, and editorial notes.

The **Usage** field does not restrict access or indexing. Optimizely Graph still indexes **Internal** categories and includes them in Graph queries. Users can still assign **Internal** categories to content in CMS. Developers decide which categories to use and filter on the **Usage** field. For example, an admin project can use **Internal** categories, and a website project can use **Public** categories.

## Edit a category

1. Go to **Settings > Categories**.
2. Select **More > Edit** on a single category.

::Image[]{src="https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/Q5uDkfzebfFxZZTrCQrnE_edit-category.png" alt="Screenshot of the Categories page where the More menu shows the Edit option" size="100" isUploading="false" position="center" width="1500" height="236" darkWidth="1500" darkHeight="236" showCaption="false" indent="1"}

:::Paragraph{indent="1"}
To bulk edit categories, select the checkbox for each category, and then select **Actions > Edit**. Select the checkbox in the header row to select all categories on the page. Selecting a parent category automatically selects all child categories.
:::

::Image[]{src="https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/2VT3vv6_FR9omEeoQ2YH9_bulk-edit-category.png" alt="Screenshot of the Categories page where selected checkboxes and the Actions menu enable bulk editing" size="100" isUploading="false" position="center" width="1374" height="676" darkWidth="1374" darkHeight="676" showCaption="false" indent="1"}

3. Update any of the following fields:
   - **Display name**
   - **Description**
   - **Visible**
   - **Selectable**
   - **Usage**
4. Click **Save**.

Changes to a category affect how it displays in selection UI and filtering. They do not change content already tagged with the category.

## Delete a category

:::hint{type="danger"}
**Warning**

Deleting a category removes it from the system along with its translations, and content tagged with the category loses that classification. To deprecate a category without losing historical associations, clear **Visible** and **Selectable** instead.
:::

1. Go to **Settings > Categories**.
2. Select **More > Delete** on a single category.

::Image[]{src="https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/vynhFdrhkzwGjR40FMyp1_delete-category.png" alt="Screenshot of the Categories page where the More menu shows the Delete option" size="100" isUploading="false" position="center" width="1486" height="187" darkWidth="1486" darkHeight="187" showCaption="false" indent="1"}

:::Paragraph{indent="1"}
To bulk delete categories, select the checkbox for each category, and then select **Actions > Delete**. Select the checkbox in the header row to select all categories on the page. Selecting a parent category automatically selects all child categories.
:::

::Image[]{src="https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/t9viZihVuw42flj3imv49_bulk-delete-category.png" alt="Screenshot of the Categories page where selected checkboxes and the Actions menu enable bulk deletion" size="100" isUploading="false" position="center" width="1359" height="678" darkWidth="1359" darkHeight="678" showCaption="false" indent="1"}

:::Paragraph{indent="1"}
If content uses the category, a warning displays. Review the associated content, and then confirm or cancel the deletion.
:::

::Image[]{src="https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/czY-N9CCCbo-dMAYntfcj_delete-category-warning.png" alt="Screenshot of the delete warning where the associated content displays for review before deletion" size="90" isUploading="false" position="center" width="580" height="361" darkWidth="580" darkHeight="361" showCaption="false" indent="1"}

3. Confirm the deletion.

## Organize hierarchies

Categories support multi-level parent-child relationships, so you can build deep taxonomies that reflect your content structure.

:::hint{type="info"}
**Note**

After you create a category, you cannot change its parent. To move a category to a different location in the hierarchy, delete the category and create a new one with the parent you want.
:::

### Best practices for hierarchies

Follow these best practices:

- **Logical grouping** – Organize categories in a way that reflects how users think about and search for content.
- **Appropriate depth** – Avoid hierarchies deeper than three or four levels because deeper hierarchies make navigation cumbersome.
- **Consistent granularity** – Ensure categories at the same level represent similar levels of specificity.

## Localize categories

Localize categories to provide translated display names and descriptions for different languages. The [languages enabled for CMS content](docId\:Py2PIByC7C-2yg37wQtml) determine which languages are available.

To provide translations:

1. Go to **Settings > Categories**.
2. Select a language from the language drop-down list.

::Image[]{src="https://api.archbee.com/api/optimize/BrbvVORKJ5iIeSMZye5kI/ISLHIa7vgpRw93rk1K9ee_category-languages.png" alt="Screenshot of the language drop-down list where you select the language to translate" size="50" isUploading="false" position="center" width="367" height="297" darkWidth="367" darkHeight="297" showCaption="false"}

3. Select **More > Edit** on the category.
4. Enter translated values in the **Display name** and **Description** fields. The edit form displays placeholder text with the default language values, such as "(en) Electronics".
5. Click **Save**.

The category **Key** remains constant across all languages because it serves as the technical identifier in APIs. CMS (SaaS) localizes only **Display name** and **Description**. Categories without translations in a language display an em dash (—) in the **Display name** column for that language. The **Key** column displays the identifier value.

## Ask Mark to maintain categories

Mark (Optimizely Agent Platform) is an agent orchestration platform that helps you work smarter in CMS (SaaS). Mark can configure and maintain the categories that organize your content. Ask Mark to list your existing categories or look up a specific one. Mark can also create, update, and remove categories, including nested categories under a parent. Describe the organization you want instead of configuring each category by hand.

Mark recognizes the words you already use. Requests that use the terms categories, labels, or tags reach the category tools. These tools manage categories only. They do not set the separate **Tags** field on a content item.

:::hint{type="info"}
**Note**

Managing categories with Mark requires CMS administrator rights.
:::