API reference products - WEBSALE Dokumentation

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	Object	Example key-value mappings.
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

{
    "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": "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

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": "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 or 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

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": "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 or 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 or 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.

https://www.<your-shop>.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:

The field active must have the value always.
Only products that are permanently active are considered.
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

{
    "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 or 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

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"
}

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": "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 or 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 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,
        "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.<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": "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

{
    "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.<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": "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 or 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

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 or 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

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 or 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

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 or 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)

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 or 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

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 or 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

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 or 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)

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 or 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

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": "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 or 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": "89.900000",
    "selection": {
        "Größe": "M"
    },
    "taxRateId": null
}

Error codes

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

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": "89.900000",
    "selection": {
        "Größe": "M"
    },
    "set": [],
    "setPrice": null,
    "taxRateId": null
}

Response

{
    "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 or 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

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 or 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

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 or 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

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 or 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

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"
        }
        "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

{
    "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 or 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

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 or 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 or 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

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

Request body

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

Response

{
    "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 or 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 or 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

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

Request body

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

Response

{
    "items": ["11-1701 M", "11-1702 L"],
    "skippedLines": []
}

Error codes

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

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 or 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 or 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

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 or 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 or 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

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,
                "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 <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": "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! <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": "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)

{
    "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 or 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

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 or 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

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 or 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

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

Response

{
    "success": true
}

Error codes

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

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 or 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

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 (e.g. 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.

API reference product ratings API reference reporter

⌘I

​Supported methods

​Data fields

​Example record

​Methods for products

​GET products

​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/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}

​Example

​Request body

​Response

​Error codes

​DELETE products/variants/{id}

​Example (attribute)

​Response (attribute)

​Example (option)

​Response (option)

​Error codes

​Methods for product variants

​GET products/{productId}/variants

​Example

​Response

​Error codes

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

​Example

​Response

​Error codes

Supported methods

Data fields

Example record

Methods for products

GET products

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/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}

Example

Request body

Response

Error codes

DELETE products/variants/{id}

Example (attribute)

Response (attribute)

Example (option)

Response (option)

Error codes

Methods for product variants

GET products/{productId}/variants

Example

Response

Error codes

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

Example

Response

Error codes