API reference template options

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 document.

Supported methods

Specification of all supported methods.

Command/Info	Endpoints	GET	POST	PUT	DELETE
Template options	templates/options/

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

https://www.<your-shop>.de/admin/api/v1/templates/options

Response

{
    "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.
403 Forbidden		You 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. 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

https://www.<your-shop>.de/admin/api/v1/templates/options/enumValue

Response

{
    "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.
403 Forbidden		You 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

https://www.<your-shop>.de/admin/api/v1/templates/options/enumValue

Request Body

{
    "label": "",
    "description": ""
}

Response

{
    "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.
403 Forbidden		You 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

https://www.<your-shop>.de/admin/api/v1/templates/options/footerShowPaymentIcon/value/payment.payment.ApplePay?subshopId=deutsch

Response

{
    "name": "footerShowPaymentIcon",
    "nodeId": "payment.payment.ApplePay",
    "value": true
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You 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

https://www.<your-shop>.de/admin/api/v1/templates/options/footerShowPaymentIcon/value/payment.payment.ApplePay?subshopId=deutsch

Request Body

{
    "value": true
}

Response

{
    "name": "footerShowPaymentIcon",
    "nodeId": "payment.payment.ApplePay",
    "value": true
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You 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 Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können.

Interfaces

Admin Interface API

Storefront API

More

Supported methods

Data fields

Methods for template options

GET templates/options

Example

Response

Filter fields

Sort fields

Error codes

GET templates/options/{name}

Example

Response

Error codes

PUT templates/options/{name}

Example

Request Body

Response

Error codes

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

Example

Response

Error codes

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

Example

Request Body

Response

Error codes

Support

​Supported methods

​Data fields

​Methods for template options

​GET templates/options

​Example

​Response

​Filter fields

​Sort fields

​Error codes

​GET templates/options/{name}

​Example

​Response

​Error codes

​PUT templates/options/{name}

​Example

​Request Body

​Response

​Error codes

​GET templates/options/{name}/value/{nodeId}

​Example

​Response

​Error codes

​PUT templates/options/{name}/value/{nodeId}

​Example

​Request Body

​Response

​Error codes

​Support

Supported methods

Data fields

Methods for template options

GET templates/options

Example

Response

Filter fields

Sort fields

Error codes

GET templates/options/{name}

Example

Response

Error codes

PUT templates/options/{name}

Example

Request Body

Response

Error codes

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

Example

Response

Error codes

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

Example

Request Body

Response

Error codes

Support