API reference products - WEBSALE Dokumentation

The /products endpoint provides an interface to manage product data and inventory in our shop system. You can use it to create, edit, filter, retrieve and delete products as well as retrieve, update and delete inventory information for products. It also covers variant attributes, product variants and set products. Bulk endpoints are available for larger volumes of data. The following overview shows which endpoints support which methods. The page then describes the data fields and time-controlled prices. After that, the individual endpoints are described, grouped by products, variant attributes, product variants, inventory and set products.

Supported methods

Command/Info	Endpoints	GET	POST	PUT	DELETE
General product	products/
General product (bulk)	bulk/products
Categories of a product	products/{productId}/categories
Product URL	products/{productId}/url
Rule test	products/testRule
Variant attributes	products/variants
Order of options	products/variants/{attributeId}/positions
Variants	products/{productId}/variants
Variant attributes of a product	products/{productId}/variantAttributes
Move variant attributes	products/{productId}/variantAttributes/move
Variants (bulk)	bulk/products/variants
General inventory	products/inventory
Inventory for products	products/{productId}/inventory
Inventory for variants	products/{productId}/variants/{variantId}/inventory
Inventory (bulk)	bulk/products/inventory
Inventory settings (bulk)	bulk/products/inventoryConfig
Set products	products/{parentProductId}/setproducts
Update set products	products/{parentProductId}/setproducts/update/{childProductId}
Set price preview	products/setproducts/preview

Data fields

Fields are managed in the configuration and stored as a JSON object in the table. A distinction is made between standard product data fields and user-defined product data fields. User-defined product data fields can be created freely, while standard product data fields are predefined by the shop and are always defined. All user-defined product data fields are found in the custom section. All other entries represent standard product data fields.

Name	Type	Meaning
active	String	Activity status of the product (for example “always”, “never”).
custom	Object	User-defined fields.
custom.liste	Array	Example list.
custom.map	Object	Example key-value mappings.
custom.validInsertCodes	Array	List of insert codes valid for this product. Each entry has a maximum of 16 characters. Only effective if the field is mapped in `content.usedFields.products.validInsertCodes` and the insert code feature is active.
custom.robotsNoFollow	Boolean	True = links to this product should not be followed by search engines.
custom.robotsNoIndex	Boolean	True = product page should not be indexed by search engines.
custom.weight	Float	Weight of the product in kilograms (for prioritization or sorting).
descr	String	Product description.
hasVariants	Boolean	Indicates whether the product has variants (for example size, colour).
id	String	Technical ID of the product.
itemNumber	String	Article number (may be identical with `id`).
name	String	Plain-text name of the product.
price	Object	Standard price of the product and its scheduled promotional prices. The structure is described in the section Time-controlled prices (promotional prices).
ratingApprovalConfig.maximumRating	Float	Maximum allowed rating (for example 5).
ratingApprovalConfig.minimumRating	Float	Minimum allowed rating (for example 0).
statistics.averageRating	Float	Average rating of the product.
statistics.ratingCount	Integer	Number of submitted ratings.
statisticsPerPoint	Array	Rating histogram as a list of `[value, count]` pairs: the number of ratings for each possible value.
taxRateId	String	ID of the applied tax rate.
timestampCreatedAt	String	Time of creation (ISO 8601 format, UTC).
timestampUpdatedAt	String	Time of the last product change (ISO 8601 format, UTC).

The fields statistics, statisticsPerPoint and ratingApprovalConfig are only returned by GET products/{productId}. The list query GET products does not contain them.

Example record

{
    "active": "always",
    "custom": {
        "liste": [
            "123",
            "234",
            "456"
        ],
        "map": {
            "a": "b",
            "c": "d",
            "e": "f"
        },
        "robotsNoFollow": false,
        "robotsNoIndex": false,
        "weight": 0.33
    },
    "descr": "Lässiges Barbour-Shirt aus Baumwoll-Piqué mit Langarm.<span class='passform'> Gearbeitet in gerader, normaler Passform (Regular Fit)</span> mit Kontrastbesatz im 'Barbour-Tartan' an der Knopfleiste und im Kragen. Mit klassischem Polokragen, Ärmelbündchen und gesticktem Barbour-Logo. Ein Mode-Klassiker für die Freizeit, in dem sich jeder Mann wohlfühlt.<span class='mass'> Länge ca. 75 cm.</span><span class='katalogfarbe'>Farbe: Navy.</span><span class='herkunft'> Original Barbour. </span>  <span class='groessen'> Größen: M (48), L (50), XL (52/54), XXL (56/58), XXXL (58/60) </span>  <span class='material'> Reine Baumwolle.</span>",
    "hasVariants": true,
    "id": "11-1701",
    "itemNumber": "11-1701",
    "name": "Tartan-Langarm-Polo in Navy",
    "price": {
        "price": "89.900000",
        "scheduledPrices": []
    },
    "ratingApprovalConfig": {
        "maximumRating": 5,
        "minimumRating": 0
    },
    "statistics": {
        "averageRating": 0,
        "ratingCount": 0
    },
    "taxRateId": "1",
    "statisticsPerPoint": [
        [
            0,
            0
        ],
        [
            1,
            0
        ],
        [
            2,
            0
        ],
        [
            3,
            0
        ],
        [
            4,
            0
        ],
        [
            5,
            0
        ]
    ],
    "timestampCreatedAt": "2024-11-14T10:41:25.000Z",
    "timestampUpdatedAt": "2025-01-24T09:28:06.000Z"
}

Time-controlled prices (promotional prices)

Products can carry prices with a validity period. This allows promotional prices to be maintained in advance, without requiring an import or a manual change at the start of the promotion. This section first describes the format of the price fields in responses, then the permitted format in requests, then the effect in the shop, and finally the validation. If you only want to know what needs to be changed in existing integrations, the short answer is in the following notice.

Breaking change in responses. Every field of type Price is no longer delivered as a string in product responses, but as an object. Affected are the base field price and all custom price fields. Integrations that further process the price directly as a string must be adjusted. The change affects all endpoints that deliver product data, so the query of individual products, list queries, the responses of Create and Update as well as the bulk endpoints.

Price fields in responses

A price field contains the standard price and the list of scheduled promotional prices. The list scheduledPrices is always present. If no promotional prices are maintained, it is delivered as an empty array.

Response (excerpt)

{
    "price": {
        "price": "19.990000",
        "scheduledPrices": [
            {
                "price": "14.990000",
                "startDate": "2026-08-01T00:00:00.000Z",
                "endDate": "2026-08-31T23:59:59.000Z",
                "promotionInfo": "Sommeraktion",
                "validForDiscount": true
            }
        ]
    }
}

Before this change, at the same location there was a plain string:

{
    "price": "19.990000"
}

Parameter overview

Parameter	Type	Description
`price`	`string`	Standard price of the field. It applies whenever no promotional price is active.
`scheduledPrices`	`array` (object)	List of scheduled promotional prices. Empty array if none are maintained.
`scheduledPrices[].price`	`string`	Promotional price for this period. Required and greater than `0`.
`scheduledPrices[].startDate`	`string`	Start of the period in ISO 8601 format (UTC). An empty string means an open start, so the entry applies from the beginning.
`scheduledPrices[].endDate`	`string`	End of the period in ISO 8601 format (UTC). An empty string means an open end, so the entry applies indefinitely.
`scheduledPrices[].promotionInfo`	`string`	Free text about the promotion, for example for labelling in the shop. The field is missing from the response if no text is set.
`scheduledPrices[].validForDiscount`	`bool`	Indicates whether further discounts on the price are granted during the promotional period. Default value `true`.

The period is inclusive at both ends. An entry with endDate set to 2026-08-31T23:59:59.000Z is still active at exactly that second.

For product variants, a price field can also be null. The type of a price field for integrations is therefore object | null. When this case occurs is described in the section Methods for product variants.

Price fields in requests

For incoming requests, the interface remains backwards compatible. A price field may still be passed as a plain string. Existing write accesses therefore continue to work unchanged. Adjustments are only needed for anyone who wants to maintain promotional prices via the interface. Alternatively, the interface accepts the object in the same structure in which it delivers it. If the field scheduledPrices is not sent, existing entries are preserved. An empty array passed in deletes all entries.

Request body (excerpt)

{
    "price": {
        "price": "19.99",
        "scheduledPrices": [
            {
                "price": "14.99",
                "startDate": "2026-08-01T00:00:00.000Z",
                "endDate": "2026-08-31T23:59:59.000Z",
                "promotionInfo": "Sommeraktion",
                "validForDiscount": true
            }
        ]
    }
}

Effect in the shop

At any point in time, exactly one price is resolved. The resolution happens anew on every request; no price is pre-calculated and stored. Which price applies is decided by three rules. First, a promotional price only takes effect if it does not exceed the standard price. Entries above the standard price are skipped during resolution. In that case the standard price remains valid. Second, with several entries active at the same time, the lowest price is used. In case of equal price, the entry with the later startDate wins, so an open start loses. If the start times are also equal, the order in the array decides. Third, an own price field on a variant replaces both the standard price and the schedule of the base product together. More on this in the section Methods for product variants.

Validation does not check a promotional price against the standard price. An entry above the standard price is stored and delivered again in the response, but never takes effect. This also applies retroactively. If the standard price is later lowered below an existing promotional price, that entry silently loses its effect.

For the search index, a restriction applies. Price fields are indexed exclusively with their standard price. Scheduled promotional prices are not available in the index and can therefore not be filtered or sorted.

Validation and error keys

Each entry is checked individually. Faulty entries result in 400 Bad Request. The error key contains the index of the affected entry in the array.

Error key	Type	Reason
`<field>.scheduledPrices[<i>]`	”invalidFormat”	The entry is not an object.
`<field>.scheduledPrices[<i>].price`	”missing”	`price` is missing or empty.
`<field>.scheduledPrices[<i>].price`	”invalidFormat”	`price` cannot be parsed as a price.
`<field>.scheduledPrices[<i>].price`	”invalidValue”	`price` is less than or equal to `0`.
`<field>.scheduledPrices[<i>].startDate`	”invalidFormat”	`startDate` is not in ISO 8601 format.
`<field>.scheduledPrices[<i>].endDate`	”invalidFormat”	`endDate` is not in ISO 8601 format.
`<field>.scheduledPrices[<i>].endDate`	”invalidValue”	`startDate` is after `endDate`.

Only the entry itself is checked. A comparison with the standard price or with other entries does not take place. Overlapping periods and prices above the standard price therefore do not cause an error, but only take effect during resolution. Which entry then applies is described in the section Effect in the shop.

Note on the internal storage format

For tools that operate directly on the stored data blob of a product or category, a special case applies. There, the two wrappers carry a different name than in the REST contract. The inner keys of an entry are identical.

Meaning	REST contract	Stored `data` blob
Standard price	`price`	`standard`
Schedule	`scheduledPrices`	`schedule`

Both read paths additionally accept the old format as a plain string. Existing data does not have to be migrated for this.

Methods for products

The endpoints documented here allow read, write, change and delete access to product data in the shop system. They can be used to manage the product catalog, both for initial population and for ongoing updates of content. In addition, endpoints are available to perform product searches based on defined rules. Since each subshop has its own product set, URLs must contain the subshopId parameter. A valid authentication is required for all endpoints. The respective permissions to read, write, create or delete products must be available.

GET products

This endpoint can be used to retrieve a list of all products in the system. Optionally, the result set can be restricted using filter parameters, for example to products assigned to a particular category (inCategory) or to be excluded from a particular category (notInCategory). Both parameters must not be used at the same time. To use this endpoint, the corresponding permissions to read products must be available.

Ordering with `inCategory`

If inCategory is used and no explicit sort parameter is specified, the endpoint returns the products exactly in the category order maintained in the shop. GET products?inCategory={categoryId} and GET categories/{categoryId}/products are equivalent here: internally, the category endpoint sets nothing other than inCategory and evaluates the same code. So there is no reason to switch to the other endpoint to get the category order.

As soon as you set a sort parameter yourself, the category order no longer applies to either of the two endpoints. Your sorting replaces it completely. If you need the original order, simply omit sort.

Example

https://www.<your-shop>.de/admin/api/v1/products?subshopId=deutsch

Response

{
    "endReached": false,
    "items": [
        {
            "active": "always",
            "custom": {
                ...
            },
            "descr": "Lässiges Barbour-Shirt aus Baumwoll-Piqué mit Langarm.<span class='passform'> Gearbeitet in gerader, normaler Passform (Regular Fit)</span> mit Kontrastbesatz im 'Barbour-Tartan' an der Knopfleiste und im Kragen. Mit klassischem Polokragen, Ärmelbündchen und gesticktem Barbour-Logo. Ein Mode-Klassiker für die Freizeit, in dem sich jeder Mann wohlfühlt.<span class='mass'> Länge ca. 75 cm.</span><span class='katalogfarbe'>Farbe: Navy.</span><span class='herkunft'> Original Barbour. </span>  <span class='groessen'> Größen: M (48), L (50), XL (52/54), XXL (56/58), XXXL (58/60) </span>  <span class='material'> Reine Baumwolle.</span>",
            "hasVariants": false,
            "id": "11-1701",
            "itemNumber": "11-1701",
            "name": "Tartan-Langarm-Polo in Navy",
            "price": {
                "price": "89.900000",
                "scheduledPrices": []
            },
            "taxRateId": "1",
            "timestampCreatedAt": "2024-11-14T10:41:25.000Z",
            "timestampUpdatedAt": "2025-01-24T09:28:06.000Z"
        }
    ],
    "nextPageToken": "MTAw",
    "searchAfterToken": "WzAuMCwiMTEtMjgxNV9kZXV0c2NoXzMiXQ",
    "totalCount": 1296
}

Filter fields

All product data fields can be filtered. User-defined fields have the custom. prefix, for example filter_eq[custom.brand]=Barbour.

Filterable does not mean “combinable with every operation”: which filter operations are permitted depends on the data type of the field. On an enum field such as active, for example, only eq and neq are permitted, contains leads to 400 Bad Request with type illegalOperation. The complete matrix can be found in API basics: Permitted operations per field type.

In addition to the product data fields, the following filters are available as plain query parameters (without the filter_ prefix and without brackets):

Parameter	Description
`inCategory={categoryId}`	Only products assigned to this category.
`notInCategory={categoryId}`	Only products not assigned to this category.
`notInAnyCategory=true`	Only products not assigned to any category.
`inSetProduct={productId}`	Only products that are part of this set product.
`notInSetProduct={productId}`	Only products that are not part of this set product.

The attributes inCategory and notInCategory, or inSetProduct and notInSetProduct, must not be set at the same time (error invalidCombination). The same applies to notInAnyCategory=true in combination with inCategory or notInCategory.

Sort fields

All product data fields except the types List, Map, Image and Video. Sorting by these types leads to an error message 400 Bad Request with type invalidValue. Syntax: sort=<field-name>:asc or sort=<field-name>:desc. The field name is mandatory. A short form such as sort=asc is a syntax error. Multiple sort criteria are passed via multiple sort parameters. For more information, see API basics: Sorting.

Other parameters

The following query parameters are also available:

Parameter	Description
`size`	Number of products per response.
`from`	Number of hits to skip (numeric offset).
`pageToken`	Token of the next page. Pass the value from `nextPageToken` of the previous response unchanged.
`searchAfterToken`	Token from the `searchAfterToken` field of the previous response. This lets you page through even very large result sets.
`textSearch`	Free text to search the products for.

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 products.
400 Bad Request		Request body could not be loaded.
400 Bad Request	”invalidValue"	"stage” is invalid. `size` is not between 1 and 300. An attempt is being made to sort products by a field of type `List`, `Map`, `Image` or `Video`.
400 Bad Request	”unknownDataField”	A filter or sort field is invalid.
400 Bad Request	”illegalOperation”	A filter type is invalid.
400 Bad Request	”invalidCharacters”	A filter value is invalid. `size` is not an integer.
400 Bad Request	”invalidCombination”	The filters `inCategory` and `notInCategory` or `inSetProduct` and `notInSetProduct` are set at the same time. `notInAnyCategory=true` is set together with `inCategory` or `notInCategory`.
503 Service Unavailable	”serviceUnavailable”	Reading data failed.

GET products/{productId}

This endpoint can be used to retrieve the complete data of a single product. Specify the product ID as a path parameter. In addition to the base data, user-defined fields are also returned. To use this endpoint, the corresponding permissions to read products must be available.

Example

https://www.<your-shop>.de/admin/api/v1/products/11-1701?subshopId=deutsch

Response

{
    "active": "always",
    "custom": {
        "liste": [
            "123",
            "234",
            "456"
        ],
        "map": {
            "a": "b",
            "c": "d",
            "e": "f"
        },
        "robotsNoFollow": false,
        "robotsNoIndex": false,
        "weight": 0.33
    },
    "descr": "Lässiges Barbour-Shirt aus Baumwoll-Piqué mit Langarm.<span class='passform'> Gearbeitet in gerader, normaler Passform (Regular Fit)</span> mit Kontrastbesatz im 'Barbour-Tartan' an der Knopfleiste und im Kragen. Mit klassischem Polokragen, Ärmelbündchen und gesticktem Barbour-Logo. Ein Mode-Klassiker für die Freizeit, in dem sich jeder Mann wohlfühlt.<span class='mass'> Länge ca. 75 cm.</span><span class='katalogfarbe'>Farbe: Navy.</span><span class='herkunft'> Original Barbour. </span>  <span class='groessen'> Größen: M (48), L (50), XL (52/54), XXL (56/58), XXXL (58/60) </span>  <span class='material'> Reine Baumwolle.</span>",
    "hasVariants": false,
    "id": "11-1701",
    "itemNumber": "11-1701",
    "name": "Tartan-Langarm-Polo in Navy",
    "price": {
        "price": "89.900000",
        "scheduledPrices": [
            {
                "price": "79.900000",
                "startDate": "2026-08-01T00:00:00.000Z",
                "endDate": "2026-08-31T23:59:59.000Z",
                "promotionInfo": "Sommeraktion",
                "validForDiscount": true
            }
        ]
    },
    "ratingApprovalConfig": {
        "maximumRating": 5.0,
        "minimumRating": 1.0
    },
    "statistics": {
        "averageRating": 4.5,
        "ratingCount": 12
    },
    "statisticsPerPoint": [
        [1, 0],
        [2, 1],
        [3, 2],
        [4, 3],
        [5, 6]
    ],
    "taxRateId": "1",
    "timestampCreatedAt": "2024-11-14T10:41:25.000Z",
    "timestampUpdatedAt": "2025-01-24T09:28:06.000Z"
}

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 products.
400 Bad Request	”invalidValue”	An invalid stage was provided.
404 Not Found		Product with `id`=`{id}` was not found.

GET products/{productId}/url

This endpoint can be used to retrieve the full URL of a product. To use this endpoint, read permissions for product data are required.

Example

https://www.<your-shop>.de/admin/api/v1/products/143-68071/url?subshopId=deutsch

Response

https://www.<your-shop>.de/SEOURL/

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 products.
400 Bad Request	”invalidValue”	An invalid stage was provided.

GET products/{productId}/categories

This endpoint lets you retrieve the categories (product groups) to which a product is assigned. The categories are listed in the order in which the assignments were created. The list is not paginated but always contains all categories of the product. Each entry has the structure of a category from the API reference categories. With the withExternData=yes parameter, each entry additionally includes _parent and _children. To use this endpoint, the corresponding permissions to read categories are required.

Example

https://www.<your-shop>.de/admin/api/v1/products/11-1701/categories?subshopId=deutsch

Response

{
    "endReached": true,
    "items": [
        {
            "active": "always",
            "custom": {},
            "descr": "",
            "hidden": false,
            "id": "942-53775",
            "name": "Poloshirts",
            "productAssignmentType": "manual",
            "productRules": "",
            "timestampCreatedAt": "2024-09-25T15:03:15.000Z",
            "timestampUpdatedAt": "2024-12-16T14:14:43.000Z"
        }
    ],
    "nextPageToken": "",
    "totalCount": 1
}

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 categories.
400 Bad Request	”invalidValue”	An invalid stage was provided.
404 Not Found		There is no product with the specified `productId`.

GET products/testRule

This endpoint can be used to selectively retrieve products that match one or more specified rules. The rules are provided as a JSON-formatted array in the query URL and allow flexible filtering by product fields such as activity status, article numbers or price values. The rules may only contain valid fields and allowed operators. To use this endpoint, the corresponding permissions to read product data must be available. The size parameter is mandatory and must contain a value between 1 and 1000. The value of a rule must always be a string, even for numeric values.

Example

The rules are encoded in the URL as a JSON array and passed via the rules parameter. To be interpreted correctly, this parameter must be URL-decoded.

https://www.<your-shop>.de/admin/api/v1/products/testRule?size=100&rules=%5B%7B%22field%22%3A%22active%22%2C%22mode%22%3A%22eq%22%2C%22value%22%3A%22always%22%7D%2C%7B%22field%22%3A%22itemNumber%22%2C%22mode%22%3A%22contains%22%2C%22value%22%3A%225%22%7D%5D

The URL queries products that meet two conditions:

The field active must have the value always.
Only permanently active products are considered.
The article number (itemNumber) must contain the digit “5”.
Only products whose article number contains a “5” somewhere are selected (for example 11-2518).

Filters and sortings on price fields access the standard price. Scheduled promotional prices are not taken into account.

Response

{
    "items": [
        {
            "active": "always",
            "custom": {
                "brand": "",
                "commission": 0,
                "commissionTaxRate": "",
                "crossSelling": [],
                "customNumber": "",
                "ean": "",
                "filterField": "",
                "image": [],
                "isbn": "",
                "mainCategory": "",
                "metaDescription": "",
                "metaDescriptionSetManually": false,
                "metaTitle": "",
                "metaTitleSetManually": false,
                "multiProducts": "",
                "oneTimeFee": 0,
                "oneTimeFeeTaxRate": "",
                "productDiscount": 0,
                "productDiscountAbsolute": false,
                "productType": "",
                "robotsNoFollow": false,
                "robotsNoIndex": false,
                "validForDiscount": false,
                "video": "",
                "voucherProductActive": false,
                "voucherProductHtmlTemplate": "",
                "voucherProductPrice": false,
                "voucherProductTemplate": "",
                "weight": 0
            },
            "descr": "Dieses weiße Poloshirt ist alles andere als gewöhnlich, sondern ...",
            "hasVariants": true,
            "id": "11-2451",
            "itemNumber": "11-2451",
            "name": "Samtweiches Polo aus Luxusjersey",
            "price": {
                "price": "89.900000",
                "scheduledPrices": []
            },
            "taxRateId": "1",
            "timestampCreatedAt": "2025-02-14T10:50:38.000Z",
            "timestampUpdatedAt": "2025-04-28T10:24:24.000Z"
        },
        {
            "active": "always",
            "custom": {
                "brand": "",
                "commission": 0,
                "commissionTaxRate": "",
                "crossSelling": [],
                "customNumber": "",
                "ean": "",
                "filterField": "",
                "image": [],
                "isbn": "",
                "mainCategory": "",
                "metaDescription": "",
                "metaDescriptionSetManually": false,
                "metaTitle": "",
                "metaTitleSetManually": false,
                "multiProducts": "",
                "oneTimeFee": 0,
                "oneTimeFeeTaxRate": "",
                "productDiscount": 0,
                "productDiscountAbsolute": false,
                "productType": "",
                "robotsNoFollow": false,
                "robotsNoIndex": false,
                "validForDiscount": false,
                "video": "",
                "voucherProductActive": false,
                "voucherProductHtmlTemplate": "",
                "voucherProductPrice": false,
                "voucherProductTemplate": "",
                "weight": 0
            },
            "descr": "Einmal angezogen, wollen Sie aus diesem kuschelig weichen Flane...",
            "hasVariants": true,
            "id": "11-2518",
            "itemNumber": "11-2518",
            "name": "Lieblingshemd aus Fischgrat-Gewebe",
            "price": {
                "price": "79.900000",
                "scheduledPrices": []
            },
            "taxRateId": "1",
            "timestampCreatedAt": "2025-02-14T10:50:45.000Z",
            "timestampUpdatedAt": "2025-04-28T10:24:24.000Z"
        },
        ...
    ],
    "nextPageToken": "WzAuMCwiMTQzLTY4MDcxX2RldXRzY2hfMyJd",
    "totalCount": 64,
    "warnings": {
        "invalidValue": [],
        "unknownFilters": [],
        "wrongOperators": []
    }
}

Possible values for `mode`

gt (greater), gte (greater or equal), lt (less), lte (less or equal), eq (equal), neq (not equal), contains (contains), notcontains (does not contain), begins (begins with), ends (ends with), within (list value contained), notwithin (list value not contained)

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 product data.
400 Bad Request		Rules could not be parsed. The `rules` parameter is not a valid JSON array, an entry does not contain `mode`, `field` or `value`, `value` is not a string, or `mode` has an unknown value.
400 Bad Request	”syntaxError”	`sort` contains more than one or no ”:“.
400 Bad Request	”unknownDataField”	A sort field is invalid.
400 Bad Request	”invalidValue”	`size` is missing or is not between 1 and 1000.

POST products

The /products endpoint can be used to create new products in the shop system. All product information required for creation must be provided in the request body. The response contains the complete product data of the newly created product in JSON format. If the provided product ID is already in use, the shop rejects the request with status 409 Conflict. An existing product is not overwritten. To create a product, the corresponding permissions are required. With the optional parameter updateIndex=yes, the search index for the product is updated immediately. Without this parameter, the next scheduled run performs the update.

Example

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

Request body

{
    "custom": {
        "liste": [],
        "map": {}
    },
    "active": "always",
    "descr": "This is a new Produkt",
    "itemNumber": "new",
    "name": "NewProdukt",
    "price": "1",
    "taxRateId": "19"
}

The price may be passed as a string, as in the example. To maintain promotional prices at the same time, use the object form described in the section Price fields in requests.

Response

{
    "active": "always",
    "custom": {
        "brand": "",
        "commission": {
            "source": "0.0",
            "parsedValue": 0
        },
        "commissionTaxRate": "",
        "crossSelling": [],
        "customNumber": "",
        "ean": "",
        "filterField": "",
        "image": [],
        "isbn": "",
        "liste": [],
        "map": {},
        ...
        "weight": {
            "source": "0.0",
            "parsedValue": 0
        }
    },
    "descr": "This is a new Produkt",
    "hasVariants": false,
    "id": "144-46864",
    "itemNumber": "new",
    "name": "NewProdukt",
    "price": {
        "price": "1.000000",
        "scheduledPrices": []
    },
    "taxRateId": "19",
    "timestampCreatedAt": "2025-05-09T14:57:36.000Z",
    "timestampUpdatedAt": "2025-05-09T14:57:36.000Z"
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to create products.
400 Bad Request		The request body could not be loaded.
400 Bad Request	”invalidValue”	An invalid stage or invalid subshop was provided. A field contains the value `null`. A value has a type that does not match the type from the configuration. A price value cannot be parsed. A field of type `Map` has a key that is not a string. A field of type `List` is not an array of strings. A time value is not in ISO 8601 format. Image data of an image is not an array of objects. `id` of the format or `path` are not strings.
400 Bad Request	”invalidFormat”	`custom` is not an object.
400 Bad Request	”unknownDataField”	A non-existent product data field was provided in the request body.
400 Bad Request	”notManualEditable”	A non-editable product data field was provided in the request body.
409 Conflict		A product with the provided `id` already exists.

Errors in scheduled promotional prices are reported per entry. The keys are described in the section Validation and error keys. If an entry in the set field refers to a non-existent product, the shop rejects the request with status code 400 Bad Request and type “notFound”. The error key is set[<i>].id, where <i> is the index of the entry in the array.

PUT products/{productId}

The products/{productId} endpoint can be used to update product data. If a product with the given ID is not found, a new product can be created automatically if the createMissing=yes parameter is set. Only the fields that are to be changed need to be specified in the request body. Fields that are not submitted keep their value. The set field replaces the members of a set product as a whole. With the optional parameter updateIndex=yes, the search index for the product is updated immediately. The optional set field can be used to assign other products to a set together with the current one. Alternatively, the set product endpoints can be used. To edit or create a product, the corresponding permissions are required.

Example

https://www.<your-shop>.de/admin/api/v1/products/11-1966

Request body

{
    "custom": {
        "brand": "",
        "commission": 0,
        "commissionTaxRate": "",
        "crossSelling": [],
        "customNumber": "",
        "ean": "",
        "filterField": "",
        "image": [],
        "isbn": "",
        "mainCategory": "",
        "metaDescription": "",
        "metaDescriptionSetManually": false,
        "metaTitle": "",
        "metaTitleSetManually": false,
        "multiProducts": "",
        "oneTimeFee": 0,
        "oneTimeFeeTaxRate": "",
        "productDiscount": 0,
        "productDiscountAbsolute": false,
        "productType": "",
        "robotsNoFollow": false,
        "robotsNoIndex": false,
        "validForDiscount": false,
        "video": "",
        "voucherProductActive": false,
        "voucherProductHtmlTemplate": "",
        "voucherProductPrice": false,
        "voucherProductTemplate": "",
        "weight": 0
    },
    "active": "always",
    "descr": "Jedes Stück, das von dem Strickunternehmen Kero Design kommt, ist ein echtes Unikat! Genau wie dieser Cardigan: Hier mischen sich zarte und kräftige Blautöne und ergeben ein effektvolles Strickkunstwerk. Diese handgestrickte Optik mit ihren schönen Farbverläufen erhält der Cardigan vor allem durch seine aufwendig von Hand gefärbten Garne. Reine Baumwolle macht die Strickjacke schön leicht und weich. Ein echter Blickfang und sehr besonders! Mit langen Ärmeln, Rundhals und Perlmutt-Knöpfen.<br /><span class='passform'> Gerade Form (Regular Fit).</span><span class='mass'> Länge ca. 60 cm.</span><span class='katalogfarbe'>Farbe: Multicolor Blue.</span><span class='herkunft'> Original Kero Design.</span>  <span class='material'>65 % Baumwolle (Bio-Baumwolle), 35 % Baumwolle.</span>",
    "itemNumber": "12-2144",
    "name": "Cardigan 'Amelia'",
    "price": {
        "price": "139.00",
        "scheduledPrices": [
            {
                "price": "119.00",
                "startDate": "2026-08-01T00:00:00.000Z",
                "endDate": "2026-08-31T23:59:59.000Z",
                "promotionInfo": "Sommeraktion",
                "validForDiscount": true
            }
        ]
    },
    "taxRateId": "1",
    "set": [
        {
            "id": "11-2497",
            "quantityFactor": 1,
            "usePrice": true,
            "fixQuantity": false,
            "hidden": false
        },
        {
            "id": "11-2492",
            "quantityFactor": 1,
            "usePrice": true,
            "fixQuantity": false,
            "hidden": false
        }
    ]
}

Response

{
    "active": "always",
    "custom": {
        "brand": "",
        "commission": 0,
        "commissionTaxRate": "",
        "crossSelling": [],
        "customNumber": "",
        "ean": "",
        "filterField": "",
        "image": [],
        "isbn": "",
        "mainCategory": "",
        "metaDescription": "",
        "metaDescriptionSetManually": false,
        "metaTitle": "",
        "metaTitleSetManually": false,
        "multiProducts": "",
        "oneTimeFee": 0,
        "oneTimeFeeTaxRate": "",
        "productDiscount": 0,
        "productDiscountAbsolute": false,
        "productType": "",
        "robotsNoFollow": false,
        "robotsNoIndex": false,
        "validForDiscount": false,
        "video": "",
        "voucherProductActive": false,
        "voucherProductHtmlTemplate": "",
        "voucherProductPrice": false,
        "voucherProductTemplate": "",
        "weight": 0
    },
    "descr": "Jedes Stück, das von dem Strickunternehmen Kero Design kommt, ist ein echtes Unikat! Genau wie dieser Cardigan: Hier mischen sich zarte und kräftige Blautöne und ergeben ein effektvolles Strickkunstwerk. Diese handgestrickte Optik mit ihren schönen Farbverläufen erhält der Cardigan vor allem durch seine aufwendig von Hand gefärbten Garne. Reine Baumwolle macht die Strickjacke schön leicht und weich. Ein echter Blickfang und sehr besonders! Mit langen Ärmeln, Rundhals und Perlmutt-Knöpfen.<br /><span class='passform'> Gerade Form (Regular Fit).</span><span class='mass'> Länge ca. 60 cm.</span><span class='katalogfarbe'>Farbe: Multicolor Blue.</span><span class='herkunft'> Original Kero Design.</span>  <span class='material'>65 % Baumwolle (Bio-Baumwolle), 35 % Baumwolle.</span>",
    "hasVariants": true,
    "id": "12-2144",
    "itemNumber": "12-2144",
    "name": "Cardigan 'Amelia'",
    "price": {
        "price": "139.000000",
        "scheduledPrices": [
            {
                "price": "119.000000",
                "startDate": "2026-08-01T00:00:00.000Z",
                "endDate": "2026-08-31T23:59:59.000Z",
                "promotionInfo": "Sommeraktion",
                "validForDiscount": true
            }
        ]
    },
    "taxRateId": "1",
    "timestampCreatedAt": "2025-02-14T10:54:45.000Z",
    "timestampUpdatedAt": "2025-05-10T16:19:36.000Z"
}

The response does not contain a set price. It is not stored but calculated on demand. How to retrieve it is described in the section POST products/setproducts/preview.

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 products.
400 Bad Request		The request body could not be loaded.
400 Bad Request	”invalidValue”	The `productId` in the path is invalid. An invalid stage or invalid subshop was provided. A field contains the value `null`. A value has a type that does not match the type from the configuration. A price value cannot be parsed. A field of type `Map` has a key that is not a string. A field of type `List` is not an array of strings. A time value is not in ISO 8601 format. Image data of an image is not an array of objects. `id` of the format or `path` are not strings.
400 Bad Request	”invalidFormat”	`custom` is not an object.
400 Bad Request	”unknownDataField”	A non-existent product data field was provided in the request body.
400 Bad Request	”notManualEditable”	A non-editable product data field was provided in the request body.
400 Bad Request	”notFound”	An entry in the `set` field refers to a product that does not exist. The error key is `set[<i>].id`.
400 Bad Request	”protectedFieldWriteError”	A protected product data field was provided in the request body and the user does not have permission to change this field.
503 Service Unavailable	”internalError”	The product could not be saved after several attempts due to version conflicts.
404 Not Found		The product with `id={id}` was not found and the `createMissing` parameter is not set to `yes`.

DELETE products/{productId}

The products/{productId} endpoint can be used to permanently delete a product with the specified ID. This process completely removes the product, including its variants, from the system. Orders that contain the product retain their data. With the optional parameter updateIndex=yes, the search index is updated immediately. To delete a product, the corresponding permissions are required.

Example

https://www.<your-shop>.de/admin/api/v1/products/123456

Response

{
    "success": 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 delete products.
400 Bad Request	”invalidValue”	An invalid stage was provided.
404 Not Found		The product with `id={id}` does not exist.

Bulk methods for products

This section describes the bulk endpoints that can be used to query or process multiple records in a single request.

POST bulk/products

Allows mass creation and updating of product data in a single request. The request body is a JSON array in which each element describes a product with an ID. Create and write permissions for products are required. By default, only products are updated. If the parameter createMissing=yes is set, products from the request that do not yet exist are automatically created. A maximum of 1000 entries can be processed in one request. This limit applies jointly to all bulk endpoints of the API. For more information, see API basics: Bulk endpoints. Errors at line level do not abort the request. Invalid or skipped entries appear in the response under skippedLines with lineNumber (counted from 0), productId, errorType (for example notFound or invalidParameters) and fieldErrors. The IDs of the written products are listed under items.

Example

https://www.<your-shop>.de/admin/api/v1/bulk/products

Request body

[
    {
        "custom": {
            "liste": [],
            "map": {}
        },
        "id": "144-46864",
        "active": "always",
        "descr": "This is a new Produkt",
        "itemNumber": "new",
        "name": "NewProdukt",
        "price": "1",
        "taxRateId": "19"
    },
    {
        "custom": {
            "liste": [],
            "map": {}
        },
        "id": "145-26318",
        "active": "always",
        "descr": "This is an existing Produkt",
        "itemNumber": "existing",
        "name": "existingProduct",
        "price": "1",
        "taxRateId": "19"
    }
]

Response

{
    "items": ["145-26318"],
    "skippedLines": [{
        "lineNumber": 0,
        "productId": "144-46864",
        "errorType": "notFound",
        "fieldErrors": {}
    }]
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to create or update products.
400 Bad Request		The request body could not be loaded. More than 1000 entries were provided.
400 Bad Request	”invalidValue”	An invalid stage or invalid subshop was provided. A field contains the value `null`. A value has a type that does not match the type from the configuration. A price value cannot be parsed. A field of type `Map` has a key that is not a string. A field of type `List` is not an array of strings. A time value is not in ISO 8601 format. Image data of an image is not an array of objects. `id` of the format or `path` are not strings.
400 Bad Request	”invalidFormat”	`custom` is not an object.
400 Bad Request	”unknownDataField”	A non-existent product data field was provided in the request body.
400 Bad Request	”notManualEditable”	A non-editable product data field was provided in the request body.

Methods for variant attributes

The endpoints in the products/variants/ area let you manage variant attributes and the related options used to form product variants in your shop. You can add new attribute options, adjust existing ones or delete attributes. You can also change the display order of the options (see PUT products/variants/{attributeId}/positions) or query individual options. For all endpoints documented here, a valid authentication is required. In addition, you need the permissions to read, create, edit or delete product variants.

GET products/variants

This endpoint can be used to retrieve a list of all variant attributes defined in the shop system and their available options. The response tells you which attribute names (for example “Size”, “Colour”) are used and which values are available per attribute. This is particularly helpful for creating or editing product variants. A valid authentication is required for this endpoint. You must have permission to read product variants. With the textSearch parameter, you can restrict the list to attributes whose name or options contain the specified text.

Example

https://www.<your-shop>.de/admin/api/v1/products/variants

Response

[
    {
        "name": "Größe",
        "options": [
            {
                "id": 1,
                "option": "L"
            },
            {
                "id": 2,
                "option": "XL"
            }
        ]
    },
    {
        "name": "Farbe",
        "options": [
            {
                "id": 4,
                "option": "Rot"
            },
            {
                "id": 3,
                "option": "Grün"
            }
        ]
    }
]

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 product variants.
400 Bad Request	”invalidValue”	An invalid stage was provided.

GET products/variants/{id}

This endpoint can be used to retrieve either a variant attribute with its associated options or a single variant option. If an attribute name (for example “Colour”) is provided in the URL, the response returns all options for this attribute. If an option ID is provided instead, the singleOption=yes parameter must additionally be set in order to retrieve the data of a specific variant option. The search by attribute name is case-insensitive. To use this endpoint, a valid authentication is required. You also need permission to read product variants.

Example (attribute)

https://www.<your-shop>.de/admin/api/v1/products/variants/Farbe

Response (attribute)

{
    "name": "Farbe",
    "options": [
        {
            "id": 4,
            "option": "Rot"
        },
        {
            "id": 3,
            "option": "Grün"
        }
    ]
}

Example (option)

https://www.<your-shop>.de/admin/api/v1/products/variants/4?singleOption=yes

Response (option)

{
    "id": 4,
    "attribute": "Farbe",
    "option": "Rot"
}

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 product variants.
400 Bad Request	”invalidValue”	An invalid stage was provided. The provided `id` is not a positive integer (with `singleOption=yes`).
404 Not Found		The option or attribute was not found.

POST products/variants

This endpoint creates a new variant attribute with arbitrary option values. If the attribute already exists (case-insensitive), it is supplemented by the new options that did not exist before. If one of the provided options already exists for the attribute, the operation is aborted with a conflict error (409). To use this endpoint, a valid authentication is required. You also need permission to create product variants.

Example

https://www.<your-shop>.de/admin/api/v1/products/variants

Request body

{
    "attribute": "color",
    "options": [
        "red",
        "blue",
        "white"
    ]
}

Response

{
    "attribute": "color",
    "options": [
        {
            "id": 23,
            "option": "red"
        },
        {
            "id": 24,
            "option": "blue"
        },
        {
            "id": 25,
            "option": "white"
        }
    ]
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to create product variants.
400 Bad Request		The request body could not be loaded.
400 Bad Request	”invalidValue”	An invalid stage was provided. `attribute` or `options` are empty. The length of `attribute` or of individual options is 0 or greater than 128 characters.
400 Bad Request	”missing”	The `attribute` or `options` parameter is missing.
400 Bad Request	”invalidFormat”	`attribute` is not a string. `options` is not an array.
400 Bad Request	”unknownDataField”	An unknown field was provided in the request body.
409 Conflict	”variantAlreadyExists”	An attribute with the provided option already exists.

PUT products/variants/{attributeId}

This endpoint updates an existing variant attribute. The search by attribute name is case-insensitive. New options can be added and existing ones can be edited. An option with an id is renamed, an option without an id is created and placed after the existing options. The renaming is applied to all products that use the option. Renaming the attribute is possible via the optional newAttributeName field in the request body. Existing options not included in the request body remain unchanged and keep their position. With the query parameter complete=true, you specify that options is the complete list of all options of the attribute. In that case, the following also applies:

Options missing from the request are removed.
All options are placed in the order of the request.
If an option to be removed is still used by a product, the shop rejects the entire request without changing anything. The response lists the affected products.

To change only the order, use PUT products/variants/{attributeId}/positions. To use this endpoint, a valid authentication is required. You also need permission to write product variants. With complete=true, you additionally need permission to delete product variants, because options can be removed in the process.

Query parameters

Parameter	Description
`complete`	`true` if `options` contains all options of the attribute. Missing options are then removed and all options are placed in the order of the request. Default: `false`

Example

https://www.<your-shop>.de/admin/api/v1/products/variants/color

Request body

{
    "options": [
        {
            "option": "blueUpd",
            "id": 24
        },
        {
            "id": 23,
            "option": "red"
        },
        {
            "id": 25,
            "option": "white"
        },
        {
            "option": "newColor"
        }
    ],
    "newAttributeName": "colorUpd"
}

Response

{
    "attribute": "colorUpd"
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to edit product variants. With `complete=true`, the permission to delete product variants is also missing.
400 Bad Request		The request body could not be loaded.
400 Bad Request	”invalidValue”	An invalid stage was provided. `options` is not an array. The length of `newAttributeName` or of individual options is 0 or greater than 128 characters. An `id` in `options` does not belong to this attribute. `complete=true` is set and `options` is empty.
400 Bad Request	”duplicateEntry”	The same `id` appears more than once in `options`.
400 Bad Request	”missing”	`attributeId` is missing.
404 Not Found		The attribute was not found.
409 Conflict	”variantInUse”	With `complete=true`: an option that would be removed is still used by a product. The response lists the affected products. Nothing was changed.
503 Internal Error	”internalError”	The update failed.

PUT products/variants/{attributeId}/positions

This endpoint lets you define the order in which the options of a variant attribute are offered. The options are placed in the order of the request. Options missing from the request follow afterwards in their previous order. Names and the options themselves do not change. The search by attribute name is case-insensitive. You specify each option by its id or by its name in option. If both are specified, the id takes precedence. To use this endpoint, a valid authentication is required. You also need permission to write product variants.

Example

https://www.<your-shop>.de/admin/api/v1/products/variants/Farbe/positions

Request body

{
    "options": [
        {
            "id": 3
        },
        {
            "option": "Rot"
        }
    ]
}

Response

The response contains the attribute with all options in the new order.

{
    "name": "Farbe",
    "options": [
        {
            "id": 3,
            "option": "Grün"
        },
        {
            "id": 4,
            "option": "Rot"
        }
    ]
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to edit product variants.
400 Bad Request		The request body could not be loaded.
400 Bad Request	”invalidValue”	An invalid stage was provided. `options` is missing or empty. An entry in `options` is not an object or does not name an option of this attribute.
400 Bad Request	”missing”	`attributeId` is missing.
404 Not Found		The attribute was not found.
503 Internal Error	”internalError”	Saving the order failed. In that case, the previous order is fully preserved.

DELETE products/variants/{id}

This endpoint lets you delete either a variant attribute together with all its options or a single option. If the attribute is currently still used by a product, the operation is aborted with a conflict error. To use this endpoint, a valid authentication is required. You also need permission to delete product variants. If an attribute name is provided in the URL, the attribute and all its options are deleted. The search by attribute name is case-insensitive. If an option ID is provided instead, the singleOption=yes parameter must additionally be set in order to delete only this single option.

Example (attribute)

https://www.<your-shop>.de/admin/api/v1/products/variants/color

Response (attribute)

{
    "success": true
}

Example (option)

https://www.<your-shop>.de/admin/api/v1/products/variants/4?singleOption=yes

Response (option)

{
    "id": 4,
    "attribute": "Farbe",
    "option": "Rot"
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to delete product variants.
400 Bad Request	”invalidValue”	An invalid stage was provided. The provided `id` is not a positive integer (with `singleOption=yes`).
404 Not Found		The option or attribute was not found.
409 Conflict	”variantInUse”	This variant attribute is used by a product variant.

Methods for product variants

The following endpoints let you manage product variants within an existing product. Variants represent specific instances of a product, for example sizes or colours, and are based on the previously defined variant attributes. The API lets you retrieve, create, update or delete variants individually. In addition, you can retrieve the variant attributes of a product, set them and change their order. Most endpoints in this section check the read, create or write permissions for product variants. Three endpoints, however, require permissions for products: deleting a variant requires the delete permission for products, retrieving the variant attributes requires the read permission, and moving a variant attribute requires the write permission. Variants also carry their price as an object. If a variant sets its own price field, this replaces both the standard price and the schedule of the base product. A variant with its own price and no promotional prices therefore does not inherit the promotion from the base product. If a variant does not set its own price field, the response returns null for this field and not the value of the base product. Integrations must handle this case; the type is object | null.

GET products/{productId}/variants

This endpoint can be used to load a list of all variants for the specified product. Variants are product versions that differ from the main product by different attribute combinations (for example size or colour). The response contains basic product data as well as the associated attribute values under selection. To use this endpoint, the corresponding permissions to read product variants are required. The response is paginated. Use size to specify how many variants a page contains (default value 10). To retrieve the next page, pass the value from nextPageToken of the previous response unchanged in the pageToken parameter. With the textSearch parameter, you can restrict the list to variants whose name, description or attribute values contain the specified text.

Example

https://www.<your-shop>.de/admin/api/v1/products/11-1701/variants

Response

{
    "endReached": true,
    "items": [
        {
            "active": "always",
            "custom": {
                "weight": 0.33
            },
            "descr": null,
            "id": "8310",
            "itemNumber": "11-1701-M",
            "name": null,
            "price": {
                "price": "89.900000",
                "scheduledPrices": []
            },
            "selection": {
                "Größe": "M"
            },
            "taxRateId": null
        },
        ...
    ],
    "nextPageToken": "MTAw",
    "totalCount": 6
}

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 product variants.
400 Bad Request	”invalidValue”	An invalid stage was provided.
404 Not Found		The product with `id={productId}` was not found.

GET products/{productId}/variants/{variantId}

This endpoint can be used to load a specific product variant by its ID within a product. The product ID is provided as part of the URL, as is the variant ID. The response contains the corresponding variant data including price, article number, selection attributes (selection) and other detail information. To use this endpoint, the corresponding permissions to read product variants are required.

Example

https://www.<your-shop>.de/admin/api/v1/products/11-1701/variants/8310

Response

{
    "active": "always",
    "custom": {
        "weight": 0.33
    },
    "descr": null,
    "id": "8310",
    "itemNumber": "11-1701-M",
    "name": null,
    "price": {
        "price": "89.900000",
        "scheduledPrices": []
    },
    "selection": {
        "Größe": "M"
    },
    "taxRateId": null
}

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 product variants.
400 Bad Request	”invalidValue”	`id` is invalid. An invalid stage was provided.
404 Not Found		Product with `id`=`{productId}` was not found. Product variant with `id={variantId}` was not found.

PUT products/{productId}/variants/{variantId}

This endpoint can be used to update the data of a specific product variant using its product ID and variant ID. The variant is identified by the given IDs. Fields that are not specified in the request body keep their value. The attribute combination (selection) must not be included in the request body and cannot be changed. To use this endpoint, write permissions for product variants are required.

Example

https://www.<your-shop>.de/admin/api/v1/products/11-1701/variants/8310

Request body

{
    "active": "always",
    "custom": {
        "weight": 0.33
    },
    "descr": null,
    "id": "8310",
    "itemNumber": "11-1701-M",
    "name": null,
    "price": {
        "price": "89.900000",
        "scheduledPrices": []
    },
    "set": [],
    "taxRateId": null
}

Response

{
    "active": "always",
    "custom": {
        "weight": 0.33
    },
    "descr": null,
    "id": "8310",
    "itemNumber": "11-1701-M",
    "name": null,
    "price": {
        "price": "89.900000",
        "scheduledPrices": []
    },
    "selection": {
        "Größe": "M"
    },
    "taxRateId": null
}

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 product variants.
400 Bad Request		The request body could not be loaded.
400 Bad Request	”invalidValue”	An invalid stage or invalid subshop was provided. `custom` is not an object. A field contains the value `null`. A value has a type that does not match the type from the configuration. A price value cannot be parsed. A field of type `Map` has a key that is not a string. A field of type `List` is not an array of strings. A time value is not in ISO 8601 format. Image data of an image is not an array of objects. `id` of the format or `path` are not strings.
400 Bad Request	”unknownDataField”	A non-existent product data field was provided in the request body, for example `selection`.
400 Bad Request	”notFound”	An entry in the `set` field refers to a product that does not exist. The error key is `set[<i>].id`.
404 Not Found		Product with `id`=`{productId}` was not found. Product variant with `id={variantId}` was not found.
400 Bad Request	”invalidFormat”	`custom` is not an object.
503 Service Unavailable	”internalError”	The product could not be saved after several attempts due to version conflicts.

GET products/{productId}/variantAttributes

This endpoint can be used to retrieve the variant attributes of a product in the order in which they are offered. Each entry contains the name of the attribute (name) and its position (position, counted from 0). The response is not paginated and endReached is always true. To use this endpoint, read permissions for products are required.

Example

https://www.<your-shop>.de/admin/api/v1/products/11-1701/variantAttributes

Response

{
    "endReached": true,
    "items": [
        {
            "name": "größe",
            "position": 0
        },
        {
            "name": "farbe",
            "position": 1
        }
    ],
    "nextPageToken": "",
    "searchAfterToken": "",
    "totalCount": 2
}

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 products.
400 Bad Request	”invalidValue”	An invalid stage was provided.
404 Not Found		The product with `id`=`{productId}` was not found.

POST products/{productId}/variantAttributes

This endpoint sets the list of variant attributes of a product by which its variants differ. Each attribute provided must exist in the shop with at least one option (see POST products/variants). The endpoint itself does not create any variants. Specific variants are created via the endpoint POST products/{productId}/variants/manage. If the product already has variant attributes and attributes are added or removed, the operation is aborted by default with a 400 error of type conflict. The reason is that all existing variants would be lost. To bypass this abort, the optional force=yes parameter can be used. In this case, all previous variants of the product are deleted and the options of the attributes on the product are reset. If the product did not yet have any variant attributes, the attributes are set without a conflict. To use this endpoint, create permissions for product variants are required.

Example

https://www.<your-shop>.de/admin/api/v1/products/11-1701/variantAttributes

Request body

{
    "attributes": [ "größe", "farbe" ]
}

Response

{
    "success": 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 create product variants.
400 Bad Request		The request body could not be loaded.
400 Bad Request	”invalidValue”	An invalid stage was provided. A provided attribute does not exist.
400 Bad Request	”missing”	`attributes` is missing in the request body.
400 Bad Request	”invalidFormat”	`attributes` is not an array. An element in `attributes` is not a string.
400 Bad Request	”unknownDataField”	An unknown field was provided in the request body.
400 Bad Request	”conflict”	The variant attributes of the product have changed. Existing variants would be deleted. Use `force=yes` to perform the operation anyway.
404 Not Found		The product with `id`=`{productId}` was not found.
503 Service Unavailable	”internalError”	The product could not be updated.

POST products/{productId}/variantAttributes/move

This endpoint can be used to move a variant attribute of a product to a new position. The position determines the order in which the attributes are offered. The product must have at least two variant attributes. To use this endpoint, write permissions for products are required.

Example

https://www.<your-shop>.de/admin/api/v1/products/11-1701/variantAttributes/move

Request body

{
    "attribute": "farbe",
    "position": 0
}

position is counted from 0 and must be less than the number of variant attributes of the product.

Response

{}

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 products.
400 Bad Request		The product has fewer than two variant attributes. The request body could not be loaded.
400 Bad Request	”invalidValue”	An invalid stage was provided. `attribute` does not exist on the product. `position` is not less than the number of variant attributes.
400 Bad Request	”missing”	`attribute` or `position` is missing from the request body.
400 Bad Request	”invalidFormat”	`attribute` is not a string. `position` is not a non-negative integer.
400 Bad Request	”unknownDataField”	An unknown field was provided in the request body.
404 Not Found		The product with `id`=`{productId}` was not found.
503 Service Unavailable	”internalError”	The attribute could not be moved or the product could not be saved.

POST products/{productId}/variants/manage

This endpoint lets you create specific variant combinations for an existing product in a targeted manner. The variant attributes of the product must first be set via the API using POST products/{productId}/variantAttributes. Only the explicitly provided combinations are created. Already existing combinations are skipped and do not appear in the response. Optionally, an id for the new variant can be provided per entry. If it is missing, the shop assigns an ID. The endpoint is particularly suitable if not all theoretically possible combinations of a product are needed, but only a specific selection. To use it, create permissions for product variants are required.

Example

https://www.<your-shop>.de/admin/api/v1/products/11-1701/variants/manage

Request body

{
    "selections": [
        {
            "größe": "M",
            "farbe": "rot"
        },
        {
            "id": "443",
            "größe": "L",
            "farbe": "blau"
        },
        ...
    ]
}

Response

{
    "items": [
        {
            "id": "42",
            "selection": {
                "größe": "M",
                "farbe": "rot"
            }
        },
        {
            "id": "443",
            "selection": {
                "größe": "L",
                "farbe": "blau"
            }
        },
        ...
    ]
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to create product variants.
400 Bad Request		The request body could not be loaded.
400 Bad Request	”invalidValue”	An invalid stage was provided. `selections` contains invalid attributes or attribute values.
400 Bad Request	”duplicateEntry”	The variant could not be created, for example because the provided `id` is already in use for this product. The error key is `selection`.
400 Bad Request	”missing”	`selections` is missing in the request body.
400 Bad Request	”invalidFormat”	`selections` is not an array. An element in `selections` is not a JSON object. An attribute value is not a string.
400 Bad Request	”unknownDataField”	An unknown field was provided in the request body.
404 Not Found		Product with `id`=`{productId}` was not found.
409 Conflict	”versionConflict”	The product was changed while the variants were being generated.

DELETE products/{productId}/variants/{variantId}

This endpoint can be used to delete an existing product variant by product ID and variant ID. This is useful, for example, when certain combinations of variants (for example size and colour) should no longer be offered. Both the parent product and the variant must exist — otherwise a corresponding error is returned. To use it, delete permissions for products are required.

Example

https://www.<your-shop>.de/admin/api/v1/products/11-1701/variants/1

Response

{
    "success": 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 delete products.
400 Bad Request	”invalidValue”	An invalid stage was provided.
404 Not Found		Product with `id`=`{productId}` was not found. Product variant with `id={variantId}` was not found.

Bulk methods for variants

This section describes the bulk endpoints that can be used to query or process multiple records in a single request.

POST bulk/products/variants

Allows mass creation and updating of product variants in a single request. The request body is a JSON array in which each element describes a product variant. Create and write permissions for product variants are required. For each entry, the respective product variant is identified by the productId, variantId and selection fields. To update a variant, productId together with selection or variantId is sufficient. When creating a new variant, selection is mandatory; if variantId is also provided, the new variant is created with this ID. By default, only product variants are updated. If the parameter createMissing=yes is set, product variants from the request that do not yet exist are automatically created. With the parameter updateIndex=yes, the search index is updated immediately. A maximum of 1000 entries can be processed in one request. This limit applies jointly to all bulk endpoints of the API. Details can be found in API basics: Bulk endpoints.

Example

https://www.<your-shop>.de/admin/api/v1/bulk/products/variants

Request body

[
    {
        "custom": {
            "liste": [],
            "map": {}
        },
        "productId": "144-46864",
        "selection": {
            "größe": "M",
            "farbe": "rot"
        },
        "active": "always",
        "descr": "This is a new Variant",
        "name": "NewVariant"
    },
    {
        "custom": {
            "liste": [],
            "map": {}
        },
        "productId": "144-46864",
        "selection": {
            "größe": "L",
            "farbe": "blau"
        },
        "active": "always",
        "descr": "This is an existing Variant",
        "name": "existingVariant"
    }
]

Response

{
    "items": [{"lineNumber": 1, "productId": "144-46864", "variantId": "43"}],
    "skippedLines": [{
        "lineNumber": 0,
        "productId": "144-46864",
        "errorType": "notFound",
        "fieldErrors": {}
    }]
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to create or update products.
400 Bad Request		The request body could not be loaded. More than 1000 entries were provided.
400 Bad Request	”invalidValue”	An invalid stage or invalid subshop was provided. A field contains the value `null`. A value has a type that does not match the type from the configuration. A price value cannot be parsed. A field of type `Map` has a key that is not a string. A field of type `List` is not an array of strings. A time value is not in ISO 8601 format. Image data of an image is not an array of objects. `id` of the format or `path` are not strings.
400 Bad Request	”invalidCombination”	Both `variantId` and `selection` were provided, but the `variantId` does not match the variant identified by `selection`.
400 Bad Request	”invalidFormat”	`custom` is not an object.
400 Bad Request	”unknownDataField”	A non-existent product data field was provided in the request body.
400 Bad Request	”notManualEditable”	A non-editable product data field was provided in the request body.

Methods for general inventory

The following endpoints let you retrieve, create, update and delete inventories in the system. Each inventory is identified by a unique inventoryId. Depending on the endpoint, inventories can be set directly or changed relatively, for example when booking additions or removals. For all endpoints documented here, a corresponding permission to access inventories is required. All endpoints in this section support the optional URL parameter storageId, with which the storage ID can be specified explicitly. If this parameter is not set, the storage ID of the active subshop is used automatically.

Where does the `inventoryId` come from?

The inventoryId is the key of the inventory entry. When a product or variant is created, the system automatically creates an inventory entry with a default key:

Object	Default `inventoryId`	Example
Product without variants	the product ID	`11-1701`
Product variant	`{productId}.{variantId}`, that is, product ID and variant ID, separated by a dot	`11-1701.M`

So you do not have to query the inventoryId separately; for the standard case, you can assemble it from the product and variant ID.

The default key is merely the initial value and does not represent a guarantee. The inventoryId of a product can be overridden. That is exactly what it is there for: multiple products or variants can share the same inventory by referring to the same inventoryId. To find out which inventoryId is actually assigned to a product, read the storeId field via the method GET products/{productId}/inventory. In integrations that work on maintained shops, do not blindly rely on the default scheme.

For the same reason, the examples in this section (for example 11-1701 M) deviate from the default scheme. They show a shop in which custom inventory keys are maintained.

GET products/inventory/{inventoryId}

This endpoint can be used to retrieve the inventory of a product or product variant by the inventory ID (inventoryId). The response contains information about the current stock, open orders and the time of the last update. To use the endpoint, the corresponding permissions to read inventories must be available.

Example

https://www.<your-shop>.de/admin/api/v1/products/inventory/11-1701%20M

Response

{
    "amount": 10.0,
    "id": "100-21456",
    "openOrder": 0.0,
    "setAt": "2024-08-19T08:03:26.000Z",
    "updatedAt": "2024-08-19T08:03:26.000Z"
}

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 inventories.
404 Not Found		No inventory with `id={inventoryId}` was found in the current subshop.

POST products/inventory

This endpoint creates a new inventory for a product or product variant. A unique inventory ID (id) is provided as well as the available and open quantities. To use this endpoint, the corresponding permissions to create inventories must be available.

Example

https://www.<your-shop>.de/admin/api/v1/products/inventory

Request body

{
    "id": "11-1701 M",
    "amount": 10.0,
    "openOrder": 0.0
}

Response

{
    "amount": 10.0,
    "id": "11-1701 M",
    "openOrder": 0.0,
    "setAt": "2025-05-01T10:12:00.000Z",
    "updatedAt": "2025-05-01T10:12:00.000Z"
}

Error codes

Error	Type	Reason
401 Unauthorized		Not authorized: you are not logged in.
403 Forbidden		You do not have the required permissions to create inventories.
400 Bad Request		The request body could not be loaded.
400 Bad Request	”missing”	The mandatory `id` field is missing in the request body.
400 Bad Request	”invalidValue”	The `id` field must not be empty.
400 Bad Request	”invalidFormat”	A field value has an incorrect data type, for example Number instead of String for `id`.
400 Bad Request	”unknownDataField”	The request body contains an unknown field.
400 Bad Request	”duplicateEntry”	An inventory with the given `id` already exists.

PUT products/inventory/{inventoryId}

This endpoint updates the inventory of a specific product using the supplied parameters. You can adjust both the stock (amount) and the number of open orders (openOrder) — either absolutely or relatively:

If amountType is set to relative, the current inventory is increased by the given amount or — if the value is negative — decreased. Otherwise, the inventory is set to the value of amount.
openOrderType works correspondingly: if it is set to relative, the number of open orders is increased or decreased (with a negative value) by openOrder. Without relative, openOrder is set directly.

If no inventory exists for the given {inventoryId}, the optional URL parameter createMissing=yes can be used to automatically create a new entry. To use this endpoint, you need permission to write inventories.

Example

https://www.<your-shop>.de/admin/api/v1/products/inventory/11-1701%20M

Request body

{
    "amount": 10.0,
    "amountType": "absolute",
    "openOrder": -1.0,
    "openOrderType": "relative"
}

Response

{
    "amount": 10.0,
    "id": "11-1701 M",
    "openOrder": 4.0,
    "setAt": "2025-05-01T14:22:30.000Z",
    "updatedAt": "2025-05-01T14:22:30.000Z"
}

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 inventories.
400 Bad Request		The request body could not be loaded.
400 Bad Request	”invalidFormat”	`amount` or `openOrder` is not a valid Number type.
404 Not Found		No inventory with `id={inventoryId}` was found in the current subshop and `createMissing` is not `yes`.

DELETE products/inventory/{inventoryId}

This endpoint deletes the inventory of a product for the given {inventoryId} in the current subshop. If no corresponding entry exists, an error is returned. To use this endpoint, you need permission to delete inventories.

Example

https://www.<your-shop>.de/admin/api/v1/products/inventory/1

Response

{
    "success": 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 delete inventories.
404 Not Found		No inventory with `id={inventoryId}` was found in the current subshop.

POST bulk/products/inventory

This endpoint lets you create or update multiple inventories in a single request (upsert). Each entry in the request body is addressed by its id (inventory ID, see Where does the inventoryId come from?). For each entry, you can adjust the stock (amount) and the number of open orders (openOrder) either absolutely or relatively:

If amountType is set to relative, the current inventory is increased by the given amount. With a negative value, it is decreased. Otherwise, the inventory is set to the value of amount.
openOrderType works correspondingly. If it is set to relative, the number of open orders is increased by openOrder or decreased with a negative value. Without relative, openOrder is set directly.
If no inventory exists yet for an id, it is created by default, provided a product or variant of the subshop references this inventoryId. With createMissing=no, only existing entries are updated.

To use this endpoint, you need permission to write inventories.

The endpoint expects POST, even when existing inventories are updated. This applies to all bulk endpoints. A PUT to bulk/products/inventory is not answered. The request goes nowhere without the inventories changing.

Changed default behavior. Previously, missing inventories were only created with createMissing=yes. Creating them is now the default. Integrations that call the endpoint without createMissing and rely on unknown IDs not being created must send createMissing=no.

A maximum of 1000 entries can be processed in one request. This limit applies jointly to all bulk endpoints of the API. For more information, see API basics: Bulk endpoints. If there are more entries, the entire request is rejected and nothing is written.

URL parameters

Parameter	Values	Default	Description
`subshopId`	Subshop ID	Header `X-SubshopId`, otherwise first subshop	Determines the subshop and therefore the default storage.
`storageId`	Storage ID	Storage of the subshop	Writes to a storage other than the default storage of the subshop.
`stage`	`work`, `active`	`work`	Content stage. Used for the reference check and the back-in-stock notifications.
`createMissing`	`yes`, `no`	`yes`	With `no`, only existing entries are updated. Unknown IDs are skipped with `notFound`.
`requireReference`	`yes`, `no`	`yes`	Protection against typos: a missing entry is only created if a product or variant of the subshop references this `inventoryId`. With `no`, the check is disabled. Only takes effect if `createMissing` is not `no`.

Existing entries are always updated, even if no product references them. requireReference only applies when creating entries. If you deliberately want to create the inventory before the associated product exists, send requireReference=no.

Fields per entry

Field	Type	Required	Description
`id`	String	yes	Inventory ID (`inventoryId`)
`amount`	Number	`amount` or `openOrder`	Stock
`amountType`	String	no	`relative`: `amount` is added to the existing value. Any other value or missing: the value is set absolutely.
`openOrder`	Number	`amount` or `openOrder`	Number of open orders
`openOrderType`	String	no	Like `amountType`, applied to `openOrder`

At least amount or openOrder must be specified. A field that is not specified remains unchanged. If an entry is newly created, a relative change counts from 0: {"id": "4800", "amount": 5, "amountType": "relative"} results in an entry with amount = 5. A field that is not specified is created with 0. All fields of an entry are checked before writing. An invalid entry is skipped completely, even if individual fields are valid.

Example

https://www.<your-shop>.de/admin/api/v1/bulk/products/inventory

Request body

The request body is a JSON array. For compatibility reasons, an object with the array in the data field is also accepted ({"data": [ ... ]}).

[
    {
        "id": "11-1701 M",
        "amount": 10.0,
        "amountType": "absolute",
        "openOrder": -1.0,
        "openOrderType": "relative"
    },
    {
        "id": "11-1702 L",
        "amount": 5.0
    },
    {
        "id": "11-1702 L",
        "amount": 1.0
    },
    {
        "id": "11-1703 XL",
        "amount": "zehn"
    }
]

Response

Line-level errors do not abort the request. Valid entries are written, invalid ones are listed in skippedLines. In both cases, the response has status 200.

{
    "items": ["11-1701 M", "11-1702 L"],
    "skippedLines": [
        {
            "lineNumber": 2,
            "inventoryId": "11-1702 L",
            "errorType": "duplicateIdInRequest",
            "fieldErrors": {}
        },
        {
            "lineNumber": 3,
            "inventoryId": "11-1703 XL",
            "errorType": "invalidParameters",
            "fieldErrors": {
                "amount": { "type": "invalidValue" }
            }
        }
    ]
}

Field	Description
`items`	IDs of all created or updated inventories
`skippedLines[].lineNumber`	Position of the entry in the request array (counted from `0`). `skippedLines` is sorted by this value.
`skippedLines[].inventoryId`	ID of the entry. Empty if no ID could be determined.
`skippedLines[].errorType`	Reason for skipping, see the following table
`skippedLines[].fieldErrors`	Errors per field, for example `{"amount": {"type": "invalidValue"}}`

Values for `errorType`

`errorType`	Reason
`invalidParameters`	The entry is not a JSON object. `amount` or `openOrder` is not a number (`type: invalidValue`). `amount` and `openOrder` are both missing (`type: missing` for both fields).
`missingId`	`id` is missing or empty.
`duplicateIdInRequest`	The `id` already occurred earlier in the same request. Only the first occurrence is written.
`notFound`	The inventory does not exist and `createMissing=no` is set.
`unreferencedId`	The inventory does not exist and no product or variant references the `id`. Does not occur if `requireReference=no` is set.

Back-in-stock

After every successful change, back-in-stock notifications are generated for all products and variants that reference the changed inventoryId. If back-in-stock is disabled in the shop, this step is skipped.

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 inventories.
400 Bad Request		The request body is empty or not valid JSON. The request body is neither an array nor an object with an array in the `data` field. More than 1000 entries were provided.
400 Bad Request	”invalidValue”	An invalid stage was provided (`errorContext.stageId`).

Methods for product inventory

The following endpoints let you manage stock-related settings for individual products. This includes both the assignment to an inventory entry and the configuration of the display in the shop, such as colored traffic-light logic, custom inventory messages and reservation times. The settings directly access the general inventories maintained via the endpoints from chapter 6. For access to these endpoints, read or write permissions for product data are required, depending on the chosen operation.

GET products/{productId}/inventory

This endpoint can be used to retrieve the inventory configuration of a specific product. This configuration includes, among other things, thresholds for traffic-light colors, custom inventory messages and the reservation duration. The storeId reference points to a general inventory entry, as managed via the inventory endpoints. To use this endpoint, read permissions for product data are required.

Example

https://www.<your-shop>.de/admin/api/v1/products/11-703/inventory

Response

{
    "active": true,
    "greenYellowBorder": 0,
    "messageLimit": 5,
    "messageMail": "m.mustermann@websale.de",
    "messageMode": "inactive",
    "redOrder": true,
    "reservationTime": 10,
    "state": "dynamic",
    "storeId": "11-1701%20M",
    "textGreen": "auf Lager",
    "textRed": "Wieder vorrätig in 1 Woche(n)",
    "textYellow": "Geringe Stückzahl",
    "useGlobalBorders": false,
    "useGlobalReservationTime": true,
    "useGlobalTexts": true,
    "yellowRedBorder": 0
}

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 product data.
400 Bad Request	”invalidValue”	An invalid stage was provided.
404 Not Found		The product with `id={productId}` was not found. No inventory is assigned to the product with `id`=`{productId}`.

PUT products/{productId}/inventory

This endpoint is used to update the inventory settings of a product. It lets you adjust, for example, the display in the shop (traffic-light logic), inventory messages or the reservation time. The storeId setting remains unchanged and does not need to be provided. To use this endpoint, write permissions for product data are required.

Example

https://www.<your-shop>.de/admin/api/v1/products/11-703/inventory

Request body

{
    "active": true,
    "greenYellowBorder": 0,
    "messageLimit": 5,
    "messageMail": "m.mustermann@websale.de",
    "messageMode": "inactive",
    "redOrder": true,
    "reservationTime": 10,
    "state": "dynamic",
    "textGreen": "auf Lager",
    "textRed": "Wieder vorrätig in 1 Woche(n)",
    "textYellow": "Geringe Stückzahl",
    "useGlobalBorders": false,
    "useGlobalReservationTime": true,
    "useGlobalTexts": true,
    "yellowRedBorder": 0
}

Response

{
    "active": true,
    "greenYellowBorder": 0,
    "messageLimit": 5,
    "messageMail": "m.mustermann@websale.de",
    "messageMode": "inactive",
    "redOrder": true,
    "reservationTime": 10,
    "state": "dynamic",
    "storeId": "11-1701%20M",
    "textGreen": "auf Lager",
    "textRed": "Wieder vorrätig in 1 Woche(n)",
    "textYellow": "Geringe Stückzahl",
    "useGlobalBorders": false,
    "useGlobalReservationTime": true,
    "useGlobalTexts": true,
    "yellowRedBorder": 0
}

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 product data.
400 Bad Request	”invalidValue”	An invalid stage was provided. `state` ∉ `{"dynamic", "green", "yellow", "redhard", "redsoft"}` `messageMode` ∉ `{"inactive", "active", "global"}`
400 Bad Request	”invalidFormat”	A field value has an incorrect data type (e.g. String instead of Boolean or Number).
400 Bad Request		The request body could not be loaded.
404 Not Found		The product with `id={productId}` was not found. No inventory is assigned to the product with `id`=`{productId}`.
503 Service Unavailable		Version conflicts: the update could not be performed after several attempts.

Methods for variant inventory

This chapter describes the endpoints for managing stock-related settings of individual product variants. As with products, you can also define specific inventory displays, traffic-light limits, custom texts and reservation times for variants. The assignment is also done via a storeId that references a centrally maintained inventory. For access, the corresponding read or write permissions on product variants are required.

GET products/{productId}/variants/{variantId}/inventory

Retrieves the inventory settings of the product variant with the given variantId. The settings include, among other things, traffic-light limits, availability display, email notifications as well as the reference (storeId) to the associated central inventory. For this query, read permissions on product variants are required.

Example

https://www.<your-shop>.de/admin/api/v1/products/11-703/variants/1/inventory

Response

{
    "active": true,
    "greenYellowBorder": 0,
    "messageLimit": 5,
    "messageMail": "m.mustermann@websale.de",
    "messageMode": "inactive",
    "redOrder": true,
    "reservationTime": 10,
    "state": "dynamic",
    "storeId": "GUT",
    "textGreen": "auf Lager",
    "textRed": "Wieder vorrätig in 1 Woche(n)",
    "textYellow": "Geringe Stückzahl",
    "useGlobalBorders": false,
    "useGlobalReservationTime": true,
    "useGlobalTexts": true,
    "yellowRedBorder": 0
}

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 product variants.
400 Bad Request	”invalidValue”	An invalid stage was provided.
404 Not Found		The product with `id={productId}` was not found. The product variant with `id={variantId}` was not found. No inventory is assigned to the product with `id`=`{productId}`.

PUT products/{productId}/variants/{variantId}/inventory

Updates the inventory settings of the product variant with the given variantId. The configurations directly affect the display in the shop and control, for example, the availability display. The link to the central inventory is established via the storeId field. For this operation, write permissions on product variants are required.

Example

https://www.<your-shop>.de/admin/api/v1/products/11-703/variants/1/inventory

Request body

{
    "active": true,
    "greenYellowBorder": 0,
    "messageLimit": 5,
    "messageMail": "m.mustermann@websale.de",
    "messageMode": "inactive",
    "redOrder": true,
    "reservationTime": 10,
    "state": "dynamic",
    "textGreen": "auf Lager",
    "textRed": "Wieder bestellbar in 1 Woche(n)",
    "textYellow": "Geringe Menge",
    "useGlobalBorders": false,
    "useGlobalReservationTime": true,
    "useGlobalTexts": true,
    "yellowRedBorder": 0
}

Response

{
    "active": true,
    "greenYellowBorder": 0,
    "messageLimit": 5,
    "messageMail": "m.mustermann@websale.de",
    "messageMode": "inactive",
    "redOrder": true,
    "reservationTime": 10,
    "state": "dynamic",
    "textGreen": "auf Lager",
    "textRed": "Wieder bestellbar in 1 Woche(n)",
    "textYellow": "Geringe Menge",
    "useGlobalBorders": false,
    "useGlobalReservationTime": true,
    "useGlobalTexts": true,
    "yellowRedBorder": 0
}

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 product variants.
400 Bad Request	”invalidValue”	An invalid stage was provided. `state` ∉ `{"dynamic", "green", "yellow", "redhard", "redsoft"}` `messageMode` ∉ `{"inactive", "active", "global"}`
400 Bad Request	”invalidFormat”	A field value has an incorrect data type (e.g. String instead of Boolean or Number).
400 Bad Request		The request body could not be loaded.
404 Not Found		The product with `id={productId}` was not found. The product variant with `id={variantId}` was not found. No inventory is assigned to the product with `id`=`{productId}`.
503 Service Unavailable		Version conflicts: the update could not be performed after several attempts.

Bulk methods for inventory settings

The following endpoint lets you maintain the inventory settings of multiple products and variants in a single request. It is the bulk counterpart to PUT products/{productId}/inventory and PUT products/{productId}/variants/{variantId}/inventory.

POST bulk/products/inventoryConfig

This endpoint lets you create or update the inventory settings of multiple products and/or variants (upsert). This includes traffic-light thresholds, texts, inventory messages, reservation times and the link to an inventory via storeId. A request may contain a mix of products and variants. Since a request can contain products and variants, you always need write permissions for product data and for product variants. The permission is checked once for the entire request. A maximum of 1000 entries can be processed in one request. This limit applies jointly to all bulk endpoints of the API. For more information, see API basics: Bulk endpoints. If there are more entries, the entire request is rejected and nothing is written.

URL parameters

Parameter	Values	Default	Description
`subshopId`	Subshop ID	Header `X-SubshopId`, otherwise first subshop	Subshop
`stage`	`work`, `active`	`work`	Content stage

Addressing

Field	Type	Required	Description
`productId`	String	yes	ID of the product
`variantId`	String	no	If the field is set, the settings of the variant are written, otherwise those of the product.

A product and its variants may occur in the same request. However, the same combination of productId and variantId may only be included once.

Settings fields

All settings fields are optional. Fields that are not specified keep their stored value. The same fields and checks apply as for the individual endpoints.

Field	Type	Description
`active`	Boolean	Inventory management active
`storeId`	String	Links the product or variant to a different `inventoryId`. An empty string (`""`) removes the link. The default key then applies again, see Where does the `inventoryId` come from?.
`state`	String	`dynamic`, `green`, `yellow`, `redhard`, `redsoft`
`useGlobalBorders`	Boolean	Use global traffic-light thresholds
`greenYellowBorder`	Number	Threshold from green to yellow
`yellowRedBorder`	Number	Threshold from yellow to red
`useGlobalTexts`	Boolean	Use global traffic-light texts
`textGreen`	String	Text for green
`textYellow`	String	Text for yellow
`textRed`	String	Text for red
`redOrder`	Boolean	Orderable when red
`useGlobalReservationTime`	Boolean	Use global reservation time
`reservationTime`	Number	Reservation time
`messageMode`	String	`inactive`, `active`, `global`
`messageLimit`	Number	Threshold for the inventory message
`messageMail`	String	Recipient of the inventory message

The product or variant must already exist. If no inventory settings exist for it yet, they are created with default values and supplemented with the values from the request. As with the individual endpoints, the search index is not updated.

Example

https://www.<your-shop>.de/admin/api/v1/bulk/products/inventoryConfig

Request body

The request body must be a JSON array. An object with the data field is not accepted here.

[
    {
        "productId": "11-703",
        "active": true,
        "state": "dynamic",
        "useGlobalBorders": false,
        "greenYellowBorder": 10,
        "yellowRedBorder": 2
    },
    {
        "productId": "11-703",
        "variantId": "1",
        "storeId": "EAN-4006381333931"
    },
    {
        "productId": "11-999",
        "active": true
    },
    {
        "productId": "11-703",
        "variantId": "2",
        "state": "orange"
    }
]

Response

Line-level errors do not abort the request. Valid entries are written, invalid ones are listed in skippedLines. In both cases, the response has status 200.

{
    "items": [
        { "lineNumber": 0, "productId": "11-703" },
        { "lineNumber": 1, "productId": "11-703", "variantId": "1" }
    ],
    "skippedLines": [
        {
            "lineNumber": 2,
            "productId": "11-999",
            "errorType": "productNotFound",
            "fieldErrors": {}
        },
        {
            "lineNumber": 3,
            "productId": "11-703",
            "variantId": "2",
            "errorType": "invalidParameters",
            "fieldErrors": {
                "state": { "type": "invalidValue" }
            }
        }
    ]
}

Field	Description
`items[]`	Successfully written entries with `lineNumber`, `productId` and, for variants, `variantId`
`skippedLines[].lineNumber`	Position of the entry in the request array (counted from `0`). `skippedLines` is sorted by this value.
`skippedLines[].productId`	ID of the product. Empty if no ID could be determined.
`skippedLines[].variantId`	Only present if the entry addresses a variant
`skippedLines[].errorType`	Reason for skipping, see the following table
`skippedLines[].fieldErrors`	Errors per field, for example `{"greenYellowBorder": {"type": "invalidFormat", "expectedType": "number"}}`

Values for `errorType`

`errorType`	Reason
`invalidParameters`	The entry is not a JSON object. A field value has an incorrect data type (`type: invalidFormat` with `expectedType`). `state` or `messageMode` contains an unknown value (`type: invalidValue`).
`missingProductId`	`productId` is missing or empty.
`duplicateEntryInRequest`	The same combination of `productId` and `variantId` already occurred earlier in the same request.
`productNotFound`	The product does not exist in the subshop or stage.
`variantNotFound`	The product exists, but the variant does not.
`versionConflict`	The entry could not be written due to parallel changes, even after several attempts. Unlike the individual endpoints (`503`), only this entry is skipped.

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 product data and product variants.
400 Bad Request		The request body is empty, not valid JSON or not an array. More than 1000 entries were provided.
400 Bad Request	”invalidValue”	An invalid stage or an invalid subshop was provided.

Using storeId, you can link multiple variants to the same inventory, for example via the EAN:

[
    { "productId": "11-703", "variantId": "1", "storeId": "EAN-4006381333931" },
    { "productId": "11-703", "variantId": "2", "storeId": "EAN-4006381333931" }
]

A single entry in POST bulk/products/inventory is then enough to set the stock of both variants:

[
    { "id": "EAN-4006381333931", "amount": 40 }
]

If back-in-stock is active in the shop, the notifications are generated for both variants. To remove the link of a variant again, send "storeId": "".

Typical import workflow

Import products

POST bulk/products creates or updates the products.

Set inventory settings

POST bulk/products/inventoryConfig sets the inventory settings. If required, you can link a different inventoryId via storeId.

Write stock

POST bulk/products/inventory writes the stock. Since requireReference is active by default, only inventoryIds that are referenced by a product or variant from the previous steps are created.

If the stock is delivered before the products, call POST bulk/products/inventory with requireReference=no.

Methods for set products

This chapter describes the endpoints for managing set products (product bundles). For access, the corresponding read, write or delete permissions on product data are required. The price of a set is not a stored value. It is calculated each time anew from the price of the main product and the prices of the sub-products. If you want to display it, retrieve it via the endpoint POST products/setproducts/preview. What this means for existing integrations is described at the end of this chapter in the section The set price is no longer stored.

GET products/{parentProductId}/setproducts

Returns a list of child products if the product with id=parentProductId has a set. Optionally, setParentProductList can contain IDs of products to whose sets the current product belongs. For this query, read permissions on product data are required. Use size to specify how many sub-products items contains. Use from to specify the starting point (counted from 0). Without size, items remains empty. totalCount and setData nevertheless contain all members of the set.

Example

https://www.<your-shop>.de/admin/api/v1/products/12-2325/setproducts?subshopId=deutsch&from=0&size=100

Response (parent product)

{
    "endReached": true,
    "isChildProduct": false,
    "items": [
        {
            "active": "always",
            "custom": {
                "brand": "",
                "commission": 0,
                "commissionTaxRate": "",
                "crossSelling": [],
                "customNumber": "",
                "ean": "",
                "filterField": "",
                "image": [],
                "isbn": "",
                "mainCategory": "",
                "metaDescription": "",
                "metaDescriptionSetManually": false,
                "metaTitle": "",
                "metaTitleSetManually": false,
                "multiProducts": "",
                "oneTimeFee": 0,
                "oneTimeFeeTaxRate": "",
                "productDiscount": 0,
                "productDiscountAbsolute": false,
                "productType": "",
                "robotsNoFollow": false,
                "robotsNoIndex": false,
                "validForDiscount": false,
                "video": "",
                "voucherProductActive": false,
                "voucherProductHtmlTemplate": "",
                "voucherProductPrice": false,
                "voucherProductTemplate": "",
                "weight": 0
            },
            "descr": "Beautiful! Mit unserer neuen, weißen Bluse mit femininen Volants an Kragen und Knopfleiste kreieren Sie im Nu lässig verspielte Looks. Das sportliche Feinoxford-Gewebe trägt sich sehr komfortabel und schmeichelt der Haut. Ein absolutes Must-have und Lieblingsteil für die neue Saison. Geschneidert <span class='passform'>in leicht taillierter Form (Regular Fit)</span> mit verdeckter Knopfleiste und gerundeter Saumlinie. <span class='mass'>Länge ca. 68 cm.</span><span class='katalogfarbe'>Farbe: Weiß.</span><span class='herkunft'>Original Herringbone.</span>  <span class='material'>Reine Baumwolle.</span>",
            "hasVariants": true,
            "id": "11-2492",
            "itemNumber": "11-2492",
            "name": "Rüschenbluse 'Florence'",
            "price": {
                "price": "69.900000",
                "scheduledPrices": []
            },
            "taxRateId": "1",
            "timestampCreatedAt": "2025-02-14T10:50:41.000Z",
            "timestampUpdatedAt": "2025-04-28T10:24:24.000Z"
        },
        {
            "active": "always",
            "custom": {
                "brand": "",
                "commission": 0,
                "commissionTaxRate": "",
                "crossSelling": [],
                "customNumber": "",
                "ean": "",
                "filterField": "",
                "image": [],
                "isbn": "",
                "mainCategory": "",
                "metaDescription": "",
                "metaDescriptionSetManually": false,
                "metaTitle": "",
                "metaTitleSetManually": false,
                "multiProducts": "",
                "oneTimeFee": 0,
                "oneTimeFeeTaxRate": "",
                "productDiscount": 0,
                "productDiscountAbsolute": false,
                "productType": "",
                "robotsNoFollow": false,
                "robotsNoIndex": false,
                "validForDiscount": false,
                "video": "",
                "voucherProductActive": false,
                "voucherProductHtmlTemplate": "",
                "voucherProductPrice": false,
                "voucherProductTemplate": "",
                "weight": 0
            },
            "descr": "Schlichter Unterziehrolli? Von wegen! Dieses Basicteil werden Sie lieben, sobald Sie es das erste Mal getragen haben. Es ist aus besonders edlem Swiss Cotton Jersey gefertigt, einem sehr feinen, samtweichen und luxuriösen Jersey mit zartem Glanz. Auf der Haut fühlt er sich wahnsinnig gut an und durch seine Elastizität ist er unendlich bequem. Der etwas weiter geschnittene Rollkragen, wird locker drapiert und engt daher überhaupt nicht ein. Tragen Sie dieses Rollkragenshirt unter Blazern, Westen, Hemdjacken oder Blusen und Sie werden nicht nur top aussehen, sondern sich auch so fühlen! <span class='passform'>Normale Form (Regular Fit).</span><span class='mass'>Länge ca. 66 cm.</span><span class='katalogfarbe'>Farbe: Ecru.</span><span class='herkunft'>Original Herringbone.</span>  <span class='material'>Reine Baumwolle.</span>",
            "hasVariants": true,
            "id": "11-2497",
            "itemNumber": "11-2497",
            "name": "Edles Rollkragenshirt",
            "price": {
                "price": "89.900000",
                "scheduledPrices": []
            },
            "taxRateId": "1",
            "timestampCreatedAt": "2025-02-14T10:50:43.000Z",
            "timestampUpdatedAt": "2025-04-28T10:24:24.000Z"
        }
    ],
    "setData": {
        "items": [
            {
                "fixQuantity": false,
                "hidden": false,
                "id": "11-2497",
                "quantityFactor": 1,
                "usePrice": true
            },
            {
                "fixQuantity": false,
                "hidden": false,
                "id": "11-2492",
                "quantityFactor": 1,
                "usePrice": true
            }
        ]
    },
    "setParentProductList": [],
    "totalCount": 2
}

Response (set child product)

{
    "endReached": true,
    "isChildProduct": true,
    "items": [],
    "setData": {},
    "setParentProductList": [
        "12-2325"
    ],
    "totalCount": 0
}

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 product data.
400 Bad Request	”invalidValue”	An invalid stage was provided.

POST products/{parentProductId}/setproducts/assign

The products from the request body are assigned to the set of the product with the ID id=parentProductId. The prodId field can contain either a single string or an array of strings. Only existing products can be assigned. If one of the products is unknown, the shop rejects the entire request and assigns none of the products. For this query, write permissions on product data are required.

Example

https://www.<your-shop>.de/admin/api/v1/products/11-2803/setproducts/assign?subshopId=deutsch

Request body

{
	"prodId": [
		"105-59442"
	]
}

Response

{
    "success": 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 product data.
400 Bad Request		Request body could not be loaded.
400 Bad Request	”invalidValue”	An invalid stage was provided.
400 Bad Request	”missing”	`prodId` is missing or empty.
400 Bad Request	”notFound”	A product from `prodId` does not exist. The error message names the affected field, with an index if there are several products, for example `prodId.[1]`.
400 Bad Request	”invalidFormat”	`prodId` is not an array of strings.
400 Bad Request	”unknownDataField”	The request body contains unknown fields.
404 Not Found		`parentProductId` is missing.

POST products/{parentProductId}/setproducts/update/{childProductId}

Data of the product with id=childProductId in the set of the product with id=parentProductId is updated. For this query, write permissions on product data are required. All five fields id, quantityFactor, usePrice, fixQuantity and hidden must be specified in the setData object. If the id names a product other than childProductId, the member is replaced by this product.

Example

https://www.<your-shop>.de/admin/api/v1/products/12-2325/setproducts/update/11-2492?subshopId=deutsch

Request body

{
    "setData": {
        "id": "11-2492",
        "quantityFactor": 1,
        "usePrice": true,
        "fixQuantity": false,
        "hidden": false
    }
}

Response

{
    "parentProductId": "12-2325",
    "childProductId": "11-2492",
    "setData": {
        "id": "11-2492",
        "quantityFactor": 1,
        "usePrice": true,
        "fixQuantity": false,
        "hidden": false
    }
}

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 product data.
400 Bad Request		Request body could not be loaded.
400 Bad Request	”invalidValue”	An invalid stage was provided.
400 Bad Request	”missing”	`setData` is missing in the request body. A field in `setData` is missing.
400 Bad Request	”invalidFormat”	`setData` is not an object. A field in `setData` has the wrong type.
400 Bad Request	”invalidValue”	`quantityFactor` is not a valid quantity.
400 Bad Request	”unknownDataField”	The request body contains unknown fields.
404 Not Found		`parentProductId` or `childProductId` is missing.

POST products/setproducts/preview

This endpoint calculates the price of a set product from the provided values and returns the result. It stores nothing. This allows the set price to be displayed already during editing, that is before the product is saved. Two values are calculated. setPrice is the sum of the price of the main product and the prices of all sub-products with usePrice. setOrgPrice is the sum of the price of the main product and the prices of all sub-products, and serves as a reference price. The prices are resolved as of the current point in time, so active promotional prices flow into both values. For this query, write permissions on product data are required.

Example

https://www.<your-shop>.de/admin/api/v1/products/setproducts/preview

Request body

{
    "parentPrice": 19.99,
    "setProducts": [
        {
            "id": "P1",
            "usePrice": true,
            "quantityFactor": 2
        },
        {
            "id": "P2",
            "usePrice": false,
            "quantityFactor": 1
        }
    ],
    "scheduledPrices": [
        {
            "price": "14.99",
            "startDate": "2026-08-01T00:00:00.000Z",
            "endDate": "2026-08-31T23:59:59.000Z",
            "promotionInfo": "Sommeraktion",
            "validForDiscount": true
        }
    ],
    "fixQuantity": false,
    "hidden": false
}

Parameter	Type	Description
`parentPrice`	`number`	Standard price of the main product. Required.
`setProducts`	`array` (object)	List of sub-products. Required.
`setProducts[].id`	`string`	ID of the sub-product.
`setProducts[].usePrice`	`bool`	Indicates whether the price of this sub-product flows into `setPrice`.
`setProducts[].quantityFactor`	`number`	Quantity with which the sub-product enters the set.
`scheduledPrices`	`array` (object)	Scheduled promotional prices of the main product. Optional. Structure as described in the section Time-controlled prices (promotional prices).
`fixQuantity`	`bool`	Optional. Applies to all sub-products jointly, not per sub-product.
`hidden`	`bool`	Optional. Applies to all sub-products jointly, not per sub-product.

Unknown IDs in setProducts are skipped without triggering an error. A typo in setProducts[].id therefore does not result in 404, but in a response with a price that is too low. Check the IDs before the call.

Response

{
    "setPrice": "29.97",
    "setOrgPrice": "39.96"
}

Both values are strings. The response in the example results from a price of 4.99 for P1 and 9.99 for P2. setPrice contains the main product and twice P1, so 19.99 plus 9.98. In setOrgPrice, P2 is additionally included because all sub-products flow into it. If all sub-products have usePrice, both values are equal.

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 product data.
400 Bad Request		Request body could not be loaded.
400 Bad Request	”missing”	`parentPrice` or `setProducts` is missing.
400 Bad Request	”invalidFormat”	A field has an unsuitable type, for example `setProducts` as an object instead of an array.
400 Bad Request	”invalidValue”	An entry in `scheduledPrices` is invalid. The error keys are described in the section Validation and error keys.

Removed endpoint. The previous endpoint PUT products/{childProductId}/setproducts/recalculate is no longer available. It calculated and stored the set price. Its replacement is POST products/setproducts/preview, which only calculates.

DELETE products/{parentProductId}/setproducts/{childProductId}

The product with id=childProductId is removed from the set of the product with id=parentProductId. If childProductId=all, all products are removed from the set. If parentProductId=all, the product with id=childProductId is removed from all sets in which it is contained. For this query, delete permissions for product data are required.

Example

https://www.<your-shop>.de/admin/api/v1/products/11-2527/setproducts/11-703

Response

{
    "success": 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 delete product data.
400 Bad Request	”invalidValue”	An invalid stage was provided.
404 Not Found		`parentProductId` or `childProductId` is missing.

The set price is no longer stored

The set price is no longer a stored value; it is calculated on demand. The implicit recalculations when creating, updating, and deleting products, in the bulk endpoints, and in the product import have been removed. For clients, this means two things. First, no endpoint delivers a stored set price any longer. Second, a client that wants to display the set price must have it calculated via the endpoint POST products/setproducts/preview.

In the shop, the set price continues to be calculated on every page load. The fields on the template object have changed for this; setPrice and the associated fields are now only available on set products. What this means for existing templates is described in the section Changes to existing templates.

Removed fields

Field	Location	Effect
`setPrice`	Base field of a product	No longer appears in product responses and is no longer read in requests. The corresponding standard product field in the configuration has also been removed.
`setOrgPrice`	Slot in `content.usedFields.products`	The slot has been removed from the configuration schema.
`double_setPrice`	Elasticsearch mapping	The index field has been removed.

The removal of double_setPrice affects all queries, filters and sortings that use this index field. Existing integrations must be reviewed and adapted before the update.

Additional references

Note about product data fields

New product data fields (additional properties, attributes or technical fields) cannot be created directly via the product API. The API is exclusively used to read and maintain existing fields. To define new fields, the configuration in the content.customProductField node must be used. → content - catalog (categories & products) There you can create individual fields with type, search relevance, mandatory status and variant properties. As soon as a field has been configured there, it is automatically available in the product API afterwards, for example in GET products or POST products.

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.

​Supported methods

​Data fields

​Example record

​Time-controlled prices (promotional prices)

​Price fields in responses

​Response (excerpt)

​Parameter overview

​Price fields in requests

​Request body (excerpt)

​Effect in the shop

​Validation and error keys

​Note on the internal storage format

​Methods for products

​GET products

​Ordering with inCategory

​Example

​Response

​Filter fields

​Sort fields

​Other parameters

​Error codes

​GET products/{productId}

​Example

​Response

​Error codes

​GET products/{productId}/url

​Example

​Response

​Error codes

​GET products/{productId}/categories

​Example

​Response

​Error codes

​GET products/testRule

​Example

​Response

​Possible values for mode

​Error codes

​POST products

​Example

​Request body

​Response

​Error codes

​PUT products/{productId}

​Example

​Request body

​Response

​Error codes

​DELETE products/{productId}

​Example

​Response

​Error codes

​Bulk methods for products

​POST bulk/products

​Example

​Request body

​Response

​Error codes

​Methods for variant attributes

​GET products/variants

​Example

​Response

​Error codes

​GET products/variants/{id}

​Example (attribute)

​Response (attribute)

​Example (option)

​Response (option)

​Error codes

​POST products/variants

​Example

​Request body

​Response

​Error codes

​PUT products/variants/{attributeId}

​Query parameters

​Example

​Request body

​Response

​Error codes

Supported methods

Data fields

Example record

Time-controlled prices (promotional prices)

Price fields in responses

Response (excerpt)

Parameter overview

Price fields in requests

Request body (excerpt)

Effect in the shop

Validation and error keys

Note on the internal storage format

Methods for products

GET products

Ordering with `inCategory`

Example

Response

Filter fields

Sort fields

Other parameters

Error codes

GET products/{productId}

Example

Response

Error codes

GET products/{productId}/url

Example

Response

Error codes

GET products/{productId}/categories

Example

Response

Error codes

GET products/testRule

Example

Response

Possible values for `mode`

Error codes

POST products

Example

Request body

Response

Error codes

PUT products/{productId}

Example

Request body

Response

Error codes

DELETE products/{productId}

Example

Response

Error codes

Bulk methods for products

POST bulk/products

Example

Request body

Response

Error codes

Methods for variant attributes

GET products/variants

Example

Response

Error codes

GET products/variants/{id}

Example (attribute)

Response (attribute)

Example (option)

Response (option)

Error codes

POST products/variants

Example

Request body

Response

Error codes

PUT products/variants/{attributeId}

Query parameters

Example

Request body

Response

Error codes