> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference template options

> Manage template options through the Admin Interface API: list defined options, read and edit their settings, and read and write their values.

The `templates/options` endpoint provides an interface for managing template options. Through this interface you can list all options defined in the template, retrieve and edit their settings, and read and save the values of individual options.

Options are defined in the template and then maintained in the Admin Interface or through this API. The definition itself (name, type, and constraints) is fixed by the template and cannot be changed through the API. How options are defined and read in the template is described in the [Options](/frontend/referenz/optionen) document.

***

## Supported methods

Specification of all supported methods.

| **Command/Info**     | **Endpoints**      | **GET**               | **POST**            | **PUT**               | **DELETE**          |
| -------------------- | ------------------ | --------------------- | ------------------- | --------------------- | ------------------- |
| **Template options** | templates/options/ | <Icon icon="check" /> | <Icon icon="ban" /> | <Icon icon="check" /> | <Icon icon="ban" /> |

## Data fields

| **Name**           | **Type**         | **Meaning**                                                                                                                    |
| ------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **name**           | String           | Unique name of the option, as defined in the template.                                                                         |
| **type**           | String           | Type of the option (`String`, `Int`, `Float`, `Bool`, or `Enum`). Determines the input mask in the Admin Interface.            |
| **constraints**    | Object           | Type-dependent constraints of the option, e.g. `values` for type `Enum` or `min`/`max` for `Int` and `Float`.                  |
| **attachTo**       | String           | Configuration type the option is bound to (e.g. `payment.payment`). If the field is empty, it is a global option.              |
| **displayOptions** | Object \| null   | Controls the display position of the option in the configuration interface via `location`. `null` if no position has been set. |
| **label**          | String           | Display label of the option. Serves display purposes only and can be edited.                                                   |
| **description**    | String           | Description of the option. Serves display purposes only and can be edited.                                                     |
| **subshopIds**     | Array of strings | List of subshops in which the option is defined (e.g. `["deutsch"]`).                                                          |

## Methods for template options

The following methods make it possible to list the defined options, read and edit their settings, and retrieve and save the values of individual options.

Their use requires the appropriate read or write permissions for template data.

### GET templates/options

This method returns a list of all options defined in the template. Each entry contains the definition of the respective option (including `name`, `type`, `constraints`, and `attachTo`) as well as the editable `label` and `description`.

The endpoint works like all other searchable API endpoints and supports filtering, sorting, and pagination.

Read permissions for template data are required.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/templates/options
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "endReached": true,
    "items": [
        {
            "attachTo": "",
            "constraints": {
                "values": [
                    "grid",
                    "list",
                    "slider"
                ]
            },
            "description": "",
            "displayOptions": null,
            "label": "",
            "name": "enumValue",
            "subshopIds": [
                "deutsch"
            ],
            "type": "Enum"
        },
        ...
    ],
    "nextPageToken": "MA",
    "totalCount": 5
}
```

#### Filter fields

`name`, `type`, `attachTo`

#### Sort fields

`name`, `type`

#### Error codes

| **Error**        | **Type**            | **Reason**                                                                                           |                                                |   |
| ---------------- | ------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------- | - |
| 401 Unauthorized |                     | Not authorized: you are not logged in or do not have the required permissions to read template data. |                                                |   |
| 400 Bad Request  | "invalidValue"      | `size` ∉ \[1;300]                                                                                    | `pageToken` is not a number or is less than 0. |   |
| 400 Bad Request  | "unknownDataField"  | A filter or sort field is invalid.                                                                   |                                                |   |
| 400 Bad Request  | "unknownOperation"  | A filter type is invalid.                                                                            |                                                |   |
| 400 Bad Request  | "invalidCharacters" | `size` is not an integer. <br /> A filter value is invalid.                                          |                                                |   |
| 400 Bad Request  | "syntaxError"       | `sort` contains more than one or no ":".                                                             |                                                |   |

### GET templates/options/\{name}

This method returns the settings of a single option by its name.

Read permissions for template data are required.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/templates/options/enumValue
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "attachTo": "",
    "constraints": {
        "values": [...]
    },
    "description": "",
    "displayOptions": null,
    "label": "",
    "name": "enumValue",
    "subshopIds": [
        "deutsch"
    ],
    "type": "Enum"
}
```

The field `constraints.values` is only present for options of type `Enum`.

#### Error codes

| **Error**        | **Type** | **Reason**                                                                                           |
| ---------------- | -------- | ---------------------------------------------------------------------------------------------------- |
| 401 Unauthorized |          | Not authorized: you are not logged in or do not have the required permissions to read template data. |
| 404 Not Found    |          | The option was not found.                                                                            |

### PUT templates/options/\{name}

This method updates the settings of an option. Only `label` and `description` can be changed. All other parameters are fixed by the definition in the template and cannot be changed through the API.

Write permissions for template data are required.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/templates/options/enumValue
```

#### Request Body

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "label": "",
    "description": ""
}
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "attachTo": "",
    "constraints": {
        "values": [...]
    },
    "description": "",
    "displayOptions": null,
    "label": "",
    "name": "enumValue",
    "subshopIds": [
        "deutsch"
    ],
    "type": "Enum"
}
```

#### Error codes

| **Error**        | **Type** | **Reason**                                                                                            |
| ---------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| 401 Unauthorized |          | Not authorized: you are not logged in or do not have the required permissions to write template data. |
| 400 Bad Request  |          | The request body could not be loaded as JSON.                                                         |
| 404 Not Found    |          | The option was not found.                                                                             |

### GET templates/options/\{name}/value/\{nodeId}

This method returns the maintained value of an option.

The parameter `{nodeId}` is only required if `attachTo` was specified in the option's definition. For global options (without `attachTo`) it is omitted.

Since the value is maintained per subshop, the URL should contain the `subshopId` parameter. If it is not provided, the first subshop of the shop is used.

Read permissions for template data are required.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/templates/options/footerShowPaymentIcon/value/payment.payment.ApplePay?subshopId=deutsch
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "name": "footerShowPaymentIcon",
    "nodeId": "payment.payment.ApplePay",
    "value": true
}
```

#### Error codes

| **Error**        | **Type** | **Reason**                                                                                           |
| ---------------- | -------- | ---------------------------------------------------------------------------------------------------- |
| 401 Unauthorized |          | Not authorized: you are not logged in or do not have the required permissions to read template data. |
| 404 Not Found    |          | The option or the value was not found.                                                               |

### PUT templates/options/\{name}/value/\{nodeId}

This method saves the value of an option.

The parameter `{nodeId}` is only required if `attachTo` was specified in the option's definition. For global options (without `attachTo`) it is omitted.

Since the value is maintained per subshop, the URL should contain the `subshopId` parameter. If it is not provided, the first subshop of the shop is used.

Write permissions for template data are required.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/templates/options/footerShowPaymentIcon/value/payment.payment.ApplePay?subshopId=deutsch
```

#### Request Body

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "value": true
}
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "name": "footerShowPaymentIcon",
    "nodeId": "payment.payment.ApplePay",
    "value": true
}
```

#### Error codes

| **Error**        | **Type** | **Reason**                                                                                            |
| ---------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| 401 Unauthorized |          | Not authorized: you are not logged in or do not have the required permissions to write template data. |
| 400 Bad Request  |          | The request body could not be loaded as JSON.                                                         |
| 404 Not Found    |          | The option was not found.                                                                             |

## Support

Bei technischen Fragen und Hilfestellungen ist unser Support-Team für Sie erreichbar: [Zum Kundenportal](https://websale.atlassian.net/servicedesk/customer/portal/6)

Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können.