---
sidebar_label: 'Categories'
sidebar_position: 5
---

# Categories

Organises items into categories and subcategory hierarchies.

**Top-level structure:**

```json
{
  "categories": {
    "<categoryId>": { ... }
  }
}
```

## Category fields

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `name` | string | Yes | Internal name used for administration purposes; not displayed to guests. |
| `title` | `translatableContent` | Yes | Display title. |
| `description` | `translatableContent` | No | Display description. |
| `images.default.url` | `translatableContent` | Yes (if `images` is present) | URL for the default category image. |
| `items` | array of `{ referencedItemId }` | Yes | Items in this category, in display order. The same item can appear in multiple categories. |
| `subcategories` | array of `{ referencedCategoryId }` | No | Child categories, in display order. A category listed here is not treated as a root category in menus that also include its parent. |
| `uiProperties` | object | No | Controls how the category is displayed. |

## Category `uiProperties` fields

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `isVisibleOnCategoryLists` | boolean | No | When `false`, hides the category from ordinary category listings. Use for upsell-only categories. Defaults to `true`. |
| `heroProductLimit` | integer | No | Maximum number of products shown before a "show more" button is displayed. |
| `productDisplayMode` | string | No | Product layout within this category. One of `"regular"`, `"emphasized"`, or `"quickaddlist"`. Defaults to `"regular"`. |

**Example:**

```json
{
  "categories": {
    "200": {
      "name": "Beverages",
      "title": {
        "value": "Beverages",
        "translations": { "sv-SE": "Drycker" }
      },
      "items": [
        { "referencedItemId": "1001" },
        { "referencedItemId": "1004" }
      ],
      "subcategories": [
        { "referencedCategoryId": "201" }
      ],
      "uiProperties": {
        "productDisplayMode": "emphasized"
      }
    }
  }
}
```