> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.
# API reference products
> Manage products, variants, and inventory through the Admin Interface API: create, edit, filter, and delete items individually or with bulk endpoints.
The `/products` endpoint provides an interface to manage product data and inventory in our shop system. You can create, edit, filter, retrieve and delete products as well as retrieve, update and delete inventory information for products.
## Supported methods
| **Command/Info** | **Endpoints** | **GET** | **POST** | **PUT** | **DELETE** |
| -------------------------- | ----------------------- | --------------------- | --------------------- | --------------------- | --------------------- |
| **General product** | products/ | | | | |
| **General product (bulk)** | bulk/products | | | | |
| **Variant attributes** | products/variants | | | | |
| **Variants** | | | | | |
| **Variants (bulk)** | bulk/products/variants | | | | |
| **General inventory** | products/inventory | | | | |
| **Inventory for products** | | | | | |
| **Inventory for variants** | | | | | |
| **Inventory (bulk)** | bulk/products/inventory | | | | |
| **Set products** | | | | | |
## 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 (e.g. "always", "never"). |
| **custom** | Object | User-defined fields. |
| **custom.liste** | Array | Example list. |
| [**custom.map**](http://custom.map) | Object | Example key-value mappings. |
| **custom.validInsertCodes** | Array | List of [insert codes](/en/frontend/funktionsubersicht/werbemittelkennzeichnung) 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 (e.g. size, color). |
| **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** | String | Standard price of the product (e.g. "89.900000"). |
| **ratingApprovalConfig.maximumRating** | Integer | Maximum allowed rating (e.g. 5). |
| **ratingApprovalConfig.minimumRating** | Integer | Minimum allowed rating (e.g. 0). |
| **setPrice** | String | Set price (for product bundles). |
| **statistics.averageRating** | Float | Average rating of the product. |
| **statistics.ratingCount** | Integer | Number of submitted ratings. |
| **statisticsPerPoint** | Array | Rating histogram: 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). |
#### Example record
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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. Gearbeitet in gerader, normaler Passform (Regular Fit) 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. Länge ca. 75 cm.Farbe: Navy. Original Barbour. Größen: M (48), L (50), XL (52/54), XXL (56/58), XXXL (58/60) Reine Baumwolle.",
"hasVariants": true,
"id": "11-1701",
"itemNumber": "11-1701",
"name": "Tartan-Langarm-Polo in Navy",
"price": "89.900000",
"ratingApprovalConfig": {
"maximumRating": 5,
"minimumRating": 0
},
"setPrice": "0.000000",
"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"
}
```
## 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, e.g. 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.
If the `inCategory` parameter is used, the products are not output in the order maintained in the shop within the category. To obtain the products in the correct order, please use the `GET categories/{categoryId}/products` endpoint.
To use this endpoint, the corresponding permissions to read products must be available.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/products?subshopId=deutsch
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"endReached": false,
"items": [
{
"active": "always",
"custom": {
...
},
"descr": "Lässiges Barbour-Shirt aus Baumwoll-Piqué mit Langarm. Gearbeitet in gerader, normaler Passform (Regular Fit) 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. Länge ca. 75 cm.Farbe: Navy. Original Barbour. Größen: M (48), L (50), XL (52/54), XXL (56/58), XXXL (58/60) Reine Baumwolle.",
"hasVariants": false,
"id": "11-1701",
"itemNumber": "11-1701",
"name": "Tartan-Langarm-Polo in Navy",
"price": "89.900000",
"setPrice": "0.000000",
"taxRateId": "1",
"timestampCreatedAt": "2024-11-14T10:41:25.000Z",
"timestampUpdatedAt": "2025-01-24T09:28:06.000Z"
}
],
"nextPageToken": "WzAuMCwiMTEtMjgxNV9kZXV0c2NoXzMiXQ",
"totalCount": 1296
}
```
#### Filter fields
All product data fields, `inCategory`, `notInCategory`, `inSetProduct`, `notInSetProduct`
#### Sort fields
All product data fields
#### Other parameters
`from`
#### 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` ∉ \[1;300]
`pageToken` is not a number or is less than 0.
`from` is greater than 9999.
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. |
| 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
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/products/11-1701?subshopId=deutsch
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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. Gearbeitet in gerader, normaler Passform (Regular Fit) 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. Länge ca. 75 cm.Farbe: Navy. Original Barbour. Größen: M (48), L (50), XL (52/54), XXL (56/58), XXXL (58/60) Reine Baumwolle.",
"hasVariants": false,
"id": "11-1701",
"itemNumber": "11-1701",
"name": "Tartan-Langarm-Polo in Navy",
"price": "89.900000",
"ratingApprovalConfig": {
"maximumRating": 5.0,
"minimumRating": 1.0
},
"setPrice": "0.000000",
"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
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/products/143-68071/url?subshopId=deutsch
```
#### Response
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..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/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.
#### 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.
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/products/testRule?size=100&rules=%5B%7B%22field%22%3A%22&active%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:
1. The field `active` must have the value `always`.
Only products that are permanently active are considered.
2. The article number (`itemNumber`) must contain the digit "5".
Only products whose article number contains a "5" somewhere are selected (e.g. `11-2518`).
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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,
"setOrgPrice": "0.000000",
"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": "89.900000",
"setPrice": "0.000000",
"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,
"setOrgPrice": "0.000000",
"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": "79.900000",
"setPrice": "0.000000",
"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)
#### 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. |
| 400 Bad Request | "syntaxError" | `sort` contains more than one or no ":". |
| 400 Bad Request | "unknownDataField" | A sort field is invalid. |
| 400 Bad Request | "invalidValue" | |
### 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.
To create a product, the corresponding permissions are required.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/products
```
#### Request body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"custom": {
"liste": [],
"map": {}
},
"active": "always",
"descr": "This is a new Produkt",
"itemNumber": "new",
"name": "NewProdukt",
"price": "1",
"taxRateId": "19"
}
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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": "1.000000",
"setPrice": "0.000000",
"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. |
### 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.
The full product data must be provided in the request body.
The optional `set` field can be used to assign other products to a set together with the current one. Alternatively, [the set product endpoints](#9-methoden-für-set-produkte) can be used.
To edit or create a product, the corresponding permissions are required.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/products/11-1966
```
#### Request body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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,
"setOrgPrice": "0.000000",
"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.
Gerade Form (Regular Fit). Länge ca. 60 cm.Farbe: Multicolor Blue. Original Kero Design. 65 % Baumwolle (Bio-Baumwolle), 35 % Baumwolle.",
"itemNumber": "12-2144",
"name": "Cardigan 'Amelia'",
"price": "139.00",
"setPrice": "0.00",
"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
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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,
"setOrgPrice": "0.000000",
"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.
Gerade Form (Regular Fit). Länge ca. 60 cm.Farbe: Multicolor Blue. Original Kero Design. 65 % Baumwolle (Bio-Baumwolle), 35 % Baumwolle.",
"hasVariants": true,
"id": "12-2144",
"itemNumber": "12-2144",
"name": "Cardigan 'Amelia'",
"price": "139.000000",
"setPrice": "259.700000",
"taxRateId": "1",
"timestampCreatedAt": "2025-02-14T10:54:45.000Z",
"timestampUpdatedAt": "2025-05-10T16:19: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 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 | "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 from the system.
To delete a product, the corresponding permissions are required.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/products/123456
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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 in the request that do not yet exist are automatically created as new ones.
A maximum of 1000 entries can be processed in one request.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/bulk/products
```
#### Request body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
[
{
"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
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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 the shop. You can add new attribute options, adjust existing ones or delete attributes. You can also change the display order of options or query individual options.
For all endpoints documented here, a valid authentication is required. Additionally, you need the permissions to read, create or edit product data.
### 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 (e.g. "Size", "Color") 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 products.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/products/variants
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
[
{
"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 (e.g. "Color") 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 need permission to read products.
#### Example (attribute)
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/products/variants/Farbe
```
#### Response (attribute)
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"name": "Farbe",
"options": [
{
"id": 4,
"option": "Rot"
},
{
"id": 3,
"option": "Grün"
}
]
}
```
#### Example (option)
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/products/variants/4?singleOption=yes
```
#### Response (option)
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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 need permission to create products.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/products/variants
```
#### Request body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"attribute": "color",
"options": [
"red",
"blue",
"white"
]
}
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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, existing ones can be edited and the order of the options can be changed. Renaming the attribute is possible via the optional `newAttributeName` parameter. Existing options not included in the request body remain unchanged.
To use this endpoint, a valid authentication is required. You need permission to write products.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/products/variants/color
```
#### Request body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"options": [
{
"option": "blueUpd",
"id": 24
},
{
"id": 23,
"option": "red"
},
{
"id": 25,
"option": "white"
},
{
"option": "newColor"
}
],
"newAttributeName": "colorUpd"
}
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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. |
| 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. |
| 400 Bad Request | "missing" | `attributeId` is missing. |
| 404 Not Found | | The attribute was not found. |
| 503 Internal Error | "internalError" | The update failed. |
### 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 need permission to delete product data.
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)
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/products/variants/color
```
#### Response (attribute)
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"success": true
}
```
#### Example (option)
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/products/variants/4?singleOption=yes
```
#### Response (option)
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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 (e.g. sizes or colors) and are based on the previously defined variant attributes. The API lets you retrieve, create, update or delete variants individually as well as generate complete variant combinations automatically.
For all endpoints in this section, the corresponding read, write or delete permissions for product variants must be available.
### 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 (such as size or color). 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.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/products/11-1701/variants
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"endReached": true,
"items": [
{
"active": "always",
"custom": {
"weight": 0.33
},
"descr": null,
"id": "8310",
"itemNumber": "11-1701-M",
"name": null,
"price": "89.900000",
"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
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/products/11-1701/variants/8310
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"active": "always",
"custom": {
"weight": 0.33
},
"descr": null,
"id": "8310",
"itemNumber": "11-1701-M",
"name": null,
"price": "89.900000",
"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 by its product ID and variant ID. The variant is identified by the given ID and overwritten with the values supplied in the request body.
To use this endpoint, write permissions for product variants are required.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/products/11-1701/variants/8310
```
#### Request body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"active": "always",
"custom": {
"weight": 0.33
},
"descr": null,
"id": "8310",
"itemNumber": "11-1701-M",
"name": null,
"price": "89.900000",
"selection": {
"Größe": "M"
},
"set": [],
"setPrice": null,
"taxRateId": null
}
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"active": "always",
"custom": {
"weight": 0.33
},
"descr": null,
"id": "8310",
"itemNumber": "11-1701-M",
"name": null,
"price": "89.900000",
"selection": {
"Größe": "M"
},
"setPrice": null,
"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. |
| 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. |
### POST products/{productId}/variantAttributes
This endpoint can be used to automatically generate variants for a specific product from the supplied attributes. Each possible combination of attribute options is created as a separate product variant.
If attributes not yet assigned to the product are added or existing attributes are removed, the operation is aborted by default and a 400 error with the error type `conflict` is returned. To bypass this abort, the optional `force=yes` parameter can be used — in this case, all previous combinations are deleted and replaced with the new ones.
To use this endpoint, write permissions for product variants are required.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/products/11-1701/variantAttributes
```
#### Request body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"attributes": [ "größe", "farbe" ]
}
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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}/variants/manage
This endpoint lets you create specific variant combinations for an existing product in a targeted manner.
Unlike the `POST products/{productId}/variantAttributes` endpoint, which automatically generates all possible combinations from the provided attributes, only the explicitly provided combinations are created here. Already existing combinations are ignored; in case of collisions, a corresponding error code is returned. Optionally, IDs can also be provided.
The endpoint is particularly suitable if not all theoretically possible combinations of a product are needed, but only a specific selection.
To use it, write permissions for product variants are required.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/products/11-1701/variants/manage
```
#### Request body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"selections": [
{
"größe": "M",
"farbe": "rot"
},
{
"id": "443",
"größe": "L",
"farbe": "blau"
},
...
]
}
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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" | A provided attribute combination already exists as a product variant. |
| 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 (e.g. size/color) 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 product variants are required.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/products/11-1701/variants/1
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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 variants. |
| 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 data in a single request. The request body is a JSON array in which each element describes a product. 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 in the request that do not yet exist are automatically created as new ones.
A maximum of 1000 entries can be processed in one request.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/bulk/products/variants
```
#### Request body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
[
{
"custom": {
"liste": [],
"map": {}
},
"productId": "144-46864",
"selection": {
"größe": "M",
"farbe": "rot"
}
"id": "",
"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
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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` that usually matches a product or variant ID.
Depending on the endpoint, inventories can be set directly or changed relatively (e.g. 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.
### 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
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/products/inventory/11-1701%20M
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/products/inventory
```
#### Request body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"id": "11-1701 M",
"amount": 10.0,
"openOrder": 0.0
}
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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 (e.g. 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
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/products/inventory/1
```
#### Request body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"amount": 10.0,
"amountType": "absolute",
"openOrder": -1.0,
"openOrderType": "relative"
}
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"amount": 15.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
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/products/inventory/1
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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. |
### PUT bulk/products/inventory
This endpoint lets you update multiple inventories at the same time. The entries to be updated are provided as an array in the request body. Each entry must contain an `id` (inventory ID). For each entry, both the stock (`amount`) and the number of open orders (`openOrder`) can be adjusted — 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 a given `id`, the optional URL parameter `createMissing=yes` can be used to automatically create a new entry. Entries with invalid data (e.g. `amount` is not a Number type) are skipped.
To use this endpoint, you need permission to write inventories.
A maximum of 1000 entries can be processed in one request.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/bulk/products/inventory?createMissing=yes
```
#### Request body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
[
{
"id": "11-1701 M",
"amount": 10.0,
"amountType": "absolute",
"openOrder": -1.0,
"openOrderType": "relative"
},
{
"id": "11-1702 L",
"amount": 5.0
}
]
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"items": ["11-1701 M", "11-1702 L"],
"skippedLines": []
}
```
#### 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.
More than 1000 entries were provided. |
| 400 Bad Request | "invalidFormat" | The `stageId` URL parameter is invalid. |
## 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
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/products/11-703/inventory
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/products/11-703/inventory
```
#### Request body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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 data 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
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/products/11-703/variants/1/inventory
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/products/11-703/variants/1/inventory
```
#### Request body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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. |
## Methods for set products
This chapter describes the endpoints for managing set products (product bundles).
For access, the corresponding read or write permissions on product data are required.
### 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.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/products/12-2325/setproducts?subshopId=deutsch&from=0&size=100
```
#### Response (parent product)
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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,
"setOrgPrice": "0.000000",
"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 in leicht taillierter Form (Regular Fit) mit verdeckter Knopfleiste und gerundeter Saumlinie. Länge ca. 68 cm.Farbe: Weiß.Original Herringbone. Reine Baumwolle.",
"hasVariants": true,
"id": "11-2492",
"itemNumber": "11-2492",
"name": "Rüschenbluse 'Florence'",
"price": "69.900000",
"setPrice": "0.000000",
"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,
"setOrgPrice": "0.000000",
"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! Normale Form (Regular Fit).Länge ca. 66 cm.Farbe: Ecru.Original Herringbone. Reine Baumwolle.",
"hasVariants": true,
"id": "11-2497",
"itemNumber": "11-2497",
"name": "Edles Rollkragenshirt",
"price": "89.900000",
"setPrice": "0.000000",
"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)
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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
Products from the request body are assigned to the set of the product with `id=parentProductId`. The `prodId` field can be either a single string or an array of strings.
For this query, write permissions on product data are required.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/products/11-2803/setproducts/assign?subshopId=deutsch
```
#### Request body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"prodId": [
"105-59442"
]
}
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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 | "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.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/products/12-2325/setproducts/update/11-2492?subshopId=deutsch
```
#### Request body
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"setData": {
"id": "11-2492",
"quantityFactor": 1,
"usePrice": true,
"fixQuantity": false,
"hidden": false
}
}
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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. |
| 400 Bad Request | "invalidFormat" | `setData` is not an object. |
| 400 Bad Request | "unknownDataField" | The request body contains unknown fields. |
| 404 Not Found | | `parentProductId` or `childProductId` is missing. |
### PUT products/{childProductId}/setproducts/recalculate
The prices of products belonging to the set of the product with `id=childProductId`, as well as of products to whose sets the product with `id=childProductId` belongs, are recalculated. Variants are taken into account.
For this query, write permissions on product data are required.
#### Example
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/products/11-2803/setproducts/recalculate
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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 | "invalidValue" | An invalid stage was provided. |
| 404 Not Found | | `childProductId` is missing. |
### 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
```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www..de/admin/api/v1/products/11-2527/setproducts/11-703
```
#### Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
"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. |
## Additional references
* [API reference image converter](/en/schnittstellen/admin-interface-api/api-referenz-bildkonverter)
* [API reference categories](/en/schnittstellen/admin-interface-api/api-referenz-kategorien)
* [API reference configuration](/en/schnittstellen/admin-interface-api/api-referenz-konfiguration)
* [API reference meta data](/en/schnittstellen/admin-interface-api/api-referenz-meta-daten)
* [API reference SEO URLs](/en/schnittstellen/admin-interface-api/api-referenz-seo-urls)
* [content - catalog (categories & products)](/en/konfiguration/content-katalog-kategorien-produkte)
## 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)](/en/konfiguration/content-katalog-kategorien-produkte)
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 (e.g. in `GET products` or `POST products`).
## Support