---
sidebar_label: 'Items'
sidebar_position: 6
---

# Items

Defines all items — products and containers — that can appear in a menu.

**Top-level structure:**

```json
{
  "items": {
    "<itemId>": { ... }
  }
}
```

## Item fields

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `type` | string | Yes | `"product"` or `"container"`. |
| `title` | `translatableContent` | Yes | Display title. |
| `name` | string | No | Internal name used for administration purposes; not displayed to guests. |
| `description` | `translatableContent` | No | Display description. |
| `images.default.url` | `translatableContent` | Yes (if `images` is present) | URL for the default image. |
| `images.double-width.url` | `translatableContent` | No | URL for a double-width image variant. |
| `uiProperties` | object | No | Controls display behaviour and guest interaction. See [`uiProperties` fields](#item-uiproperties-fields). |
| `productionInformation` | object | No | Production time and point configuration. See [`productionInformation` fields](#productioninformation-fields). |
| `isMetadataItem` | boolean | No | When `true`, this item is not counted as a selectable purchasable item (e.g. a delivery fee). Defaults to `false`. |
| `usePriceFromItem` | `referencedItem` | No | Resolves this item's price from the referenced item instead. See [`referencedItem` fields](#referenceditem-fields). |
| `configItems` | array of `referencedItem` | No | Child items available in this container's configurator. |
| `selectionOptions.min` | integer | No | Minimum number of `configItems` the guest must select. |
| `selectionOptions.max` | integer | No | Maximum number of `configItems` the guest may select. |
| `badges` | array of `{ url: translatableContent }` | No | Badge images displayed on the item. |
| `tags` | array of strings | No | Tags for filtering or categorisation. |
| `alternateFor` | array of `referencedItem` | No | Items this item serves as an alternate for. |
| `barcodes` | array of strings | No | Barcodes associated with the item. |
| `mappingDetails` | object | No | Free-form metadata for external system mapping. |

## Item `uiProperties` fields

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `configurator.type` | string | No | Configurator style: `"default"` or `"meal"`. Defaults to `"default"`. |
| `desired.enableQuickAdd` | boolean | No | Shows a quick-add button so guests can add the item without opening the configurator. Defaults to `false`. |
| `desired.enableQuickConfigurator` | boolean | No | Shows a compact inline configurator on the product listing (e.g. for selecting drink size). Defaults to `false`. |
| `desired.enableConfigurator` | boolean | No | Shows a configurator button alongside the quick-add button. Defaults to `false`. |
| `desired.isVisibleOnReceipt` | boolean | No | When `false` and the item has no price, the item is omitted from the receipt and only its children are rendered. Defaults to `true`. |
| `desired.isIgnoredByConfigurator` | boolean | No | When `true`, the configurator skips this item. Defaults to `false`. |
| `desired.isNegated` | boolean | No | Reverses the selection display in the GUI. Used for "remove" containers. Defaults to `false`. |
| `guestMessages` | array of `guestMessage` | No | Messages shown to the guest when this item is interacted with. |

## `guestMessage` fields

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `textKey` | string | Yes | The message to display. One of `"guestmessages.gluten"`, `"guestmessages.alcohol"`, or `"guestmessages.nicotine"`. |
| `type` | string | No | `"Once"` shows the message only the first time it is triggered per order. `"Always"` shows it every time. Defaults to `"Always"`. |

## `productionInformation` fields

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `minDuration` | string | Yes | Minimum production duration in ISO 8601 duration format (e.g. `"PT10M"`). |
| `maxDuration` | string | No | Maximum production duration in ISO 8601 duration format. |
| `points` | integer | No | Production points assigned to this item. |

## `referencedItem` fields

Used in `configItems`, `usePriceFromItem`, and `alternateFor`.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `referencedItemId` | string (numeric) | Yes | ID of the referenced item. |
| `mapPriceGroups` | object | No | Maps source price group IDs to target price group IDs, enabling a different price group for this subtree. The mapped group must use the same currency. |
| `isSelected` | boolean | No | Whether the item is pre-selected in the configurator. Defaults to `false`. |

**Example:**

```json
{
  "items": {
    "1001": {
      "type": "product",
      "name": "Latte",
      "title": { "value": "Latte" },
      "uiProperties": {
        "desired": {
          "enableQuickAdd": true
        }
      }
    },
    "1002": {
      "type": "container",
      "title": { "value": "Size" },
      "configItems": [
        { "referencedItemId": "1003", "isSelected": true },
        { "referencedItemId": "1004" }
      ],
      "selectionOptions": { "min": 1, "max": 1 }
    }
  }
}
```