/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
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 thecustom section. All other entries represent standard product data fields.
Example record
Time-controlled prices (promotional prices)
Products can carry prices with a validity period. This allows promotional prices to be maintained in advance, without requiring an import or a manual change at the start of the promotion. This section first describes the format of the price fields in responses, then the permitted format in requests, then the effect in the shop, and finally the validation. If you only want to know what needs to be changed in existing integrations, the short answer is in the following notice.Price fields in responses
A price field contains the standard price and the list of scheduled promotional prices. The listscheduledPrices is always present. If no promotional prices are maintained, it is delivered as an empty array.
Response (excerpt)
Parameter overview
The period is inclusive at both ends. An entry with
endDate set to 2026-08-31T23:59:59.000Z is still active at exactly that second.null. The type of a price field for integrations is therefore object | null. When this case occurs is described in the section Methods for product variants.
Price fields in requests
For incoming requests, the interface remains backwards compatible. A price field may still be passed as a plain string. Existing write accesses therefore continue to work unchanged. Adjustments are only needed for anyone who wants to maintain promotional prices via the interface. Alternatively, the interface accepts the object in the same structure in which it delivers it. If the fieldscheduledPrices is not sent, existing entries are preserved. An empty array passed in deletes all entries.
Request body (excerpt)
Effect in the shop
At any point in time, exactly one price is resolved. The resolution happens anew on every request; no price is pre-calculated and stored. Which price applies is decided by three rules. First, a promotional price only takes effect if it does not exceed the standard price. Entries above the standard price are skipped during resolution. In that case the standard price remains valid. Second, with several entries active at the same time, the lowest price is used. In case of equal price, the entry with the laterstartDate wins, so an open start loses. If the start times are also equal, the order in the array decides.
Third, an own price field on a variant replaces both the standard price and the schedule of the base product together. More on this in the section Methods for product variants.
For the search index, a restriction applies. Price fields are indexed exclusively with their standard price. Scheduled promotional prices are not available in the index and can therefore not be filtered or sorted.
Validation and error keys
Each entry is checked individually. Faulty entries result in400 Bad Request. The error key contains the index of the affected entry in the array.
Only the entry itself is checked. A comparison with the standard price or with other entries does not take place. Overlapping periods and prices above the standard price therefore do not cause an error, but only take effect during resolution. Which entry then applies is described in the section Effect in the shop.
Note on the internal storage format
For tools that operate directly on the stored data blob of a product or category, a special case applies. There, the two wrappers carry a different name than in the REST contract. The inner keys of an entry are identical.
Both read paths additionally accept the old format as a plain string. Existing data does not have to be migrated for this.
Methods for products
The endpoints documented here allow read, write, change and delete access to product data in the shop system. They can be used to manage the product catalog, both for initial population and for ongoing updates of content. In addition, endpoints are available to perform product searches based on defined rules. Since each subshop has its own product set, URLs must contain thesubshopId parameter.
A valid authentication is required for all endpoints. The respective permissions to read, write, create or delete products must be available.
GET products
This endpoint can be used to retrieve a list of all products in the system. Optionally, the result set can be restricted using filter parameters, for example to products assigned to a particular category (inCategory) or to be excluded from a particular category (notInCategory). Both parameters must not be used at the same time.
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
Response
Filter fields
All product data fields,inCategory, notInCategory, inSetProduct, notInSetProduct
Sort fields
All product data fieldsOther parameters
from
Error codes
GET products/
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
Response
Error codes
GET products//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
Response
Error codes
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 therules parameter. To be interpreted correctly, this parameter must be URL-decoded.
- The field
activemust have the valuealways.
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 (for example11-2518).
Filters and sortings on price fields access the standard price. Scheduled promotional prices are not taken into account.
Response
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
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
Request body
Response
Error codes
Errors in scheduled promotional prices are reported per entry. The keys are described in the section Validation and error keys.
PUT products/
Theproducts/{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
Request body
Response
The response does not contain a set price. It is not stored but calculated on demand. How to retrieve it is described in the section POST products/setproducts/preview.
Error codes
DELETE products/
Theproducts/{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
Response
Error codes
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
Request body
Response
Error codes
Methods for variant attributes
The endpoints in theproducts/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 (for example “Size”, “Colour”) are used and which values are available per attribute. This is particularly helpful for creating or editing product variants. A valid authentication is required for this endpoint. You must have permission to read products.Example
Response
Error codes
GET products/variants/
This endpoint can be used to retrieve either a variant attribute with its associated options or a single variant option. If an attribute name (for example “Colour”) is provided in the URL, the response returns all options for this attribute. If an option ID is provided instead, thesingleOption=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)
Response (attribute)
Example (option)
Response (option)
Error codes
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
Request body
Response
Error codes
PUT products/variants/
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 optionalnewAttributeName 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
Request body
Response
Error codes
DELETE products/variants/
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, thesingleOption=yes parameter must additionally be set in order to delete only this single option.
Example (attribute)
Response (attribute)
Example (option)
Response (option)
Error codes
Methods for product variants
The following endpoints let you manage product variants within an existing product. Variants represent specific instances of a product (for example sizes or colours) and are based on the previously defined variant attributes. The API lets you retrieve, create, update or delete variants individually 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. Variants also carry their price as an object. If a variant sets its own price field, this replaces both the standard price and the schedule of the base product. A variant with its own price and no promotional prices therefore does not inherit the promotion from the base product. If a variant does not set its own price field, the response returnsnull for this field and not the value of the base product. Integrations must handle this case; the type is object | null.
GET products//variants
This endpoint can be used to load a list of all variants for the specified product. Variants are product versions that differ from the main product by different attribute combinations (for example size or colour). The response contains basic product data as well as the associated attribute values underselection.
To use this endpoint, the corresponding permissions to read product variants are required.
Example
Response
Error codes
GET products//variants/
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
Response
Error codes
PUT products//variants/
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
Request body
Response
Error codes
POST products//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 typeconflict 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
Request body
Response
Error codes
POST products//variants/manage
This endpoint lets you create specific variant combinations for an existing product in a targeted manner. Unlike thePOST 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
Request body
Response
Error codes
DELETE products//variants/
This endpoint can be used to delete an existing product variant by product ID and variant ID. This is useful, for example, when certain combinations of variants (for example size and colour) should no longer be offered. Both the parent product and the variant must exist — otherwise a corresponding error is returned. To use it, delete permissions for product variants are required.Example
Response
Error codes
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 theproductId, 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
Request body
Response
Error codes
Methods for general inventory
The following endpoints let you retrieve, create, update and delete inventories in the system. Each inventory is identified by a uniqueinventoryId that usually matches a product or variant ID.
Depending on the endpoint, inventories can be set directly or changed relatively, for example when booking additions or removals.
For all endpoints documented here, a corresponding permission to access inventories is required.
All endpoints in this section support the optional URL parameter storageId, with which the storage ID can be specified explicitly. If this parameter is not set, the storage ID of the active subshop is used automatically.
GET products/inventory/
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
Response
Error codes
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
Request body
Response
Error codes
PUT products/inventory/
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
amountTypeis set torelative, the current inventory is increased by the givenamountor — if the value is negative — decreased. Otherwise, the inventory is set to the value ofamount. openOrderTypeworks correspondingly: if it is set torelative, the number of open orders is increased or decreased (with a negative value) byopenOrder. Withoutrelative,openOrderis set directly.
{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
Request body
Response
Error codes
DELETE products/inventory/
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
Response
Error codes
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 anid (inventory ID). For each entry, both the stock (amount) and the number of open orders (openOrder) can be adjusted — either absolutely or relatively:
- If
amountTypeis set torelative, the current inventory is increased by the givenamountor — if the value is negative — decreased. Otherwise, the inventory is set to the value ofamount. openOrderTypeworks correspondingly: if it is set torelative, the number of open orders is increased or decreased (with a negative value) byopenOrder. Withoutrelative,openOrderis set directly.- If no inventory exists for a given
id, the optional URL parametercreateMissing=yescan be used to automatically create a new entry. Entries with invalid data are skipped, for example whenamountis not a Number type.
Example
Request body
Response
Error codes
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//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. ThestoreId 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
Response
Error codes
PUT products//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. ThestoreId setting remains unchanged and does not need to be provided.
To use this endpoint, write permissions for product data are required.
Example
Request body
Response
Error codes
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 astoreId that references a centrally maintained inventory.
For access, the corresponding read or write permissions on product data are required.
GET products//variants//inventory
Retrieves the inventory settings of the product variant with the givenvariantId.
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
Response
Error codes
PUT products//variants//inventory
Updates the inventory settings of the product variant with the givenvariantId.
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
Request body
Response
Error codes
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. The price of a set is not a stored value. It is calculated each time anew from the price of the main product and the prices of the sub-products. If you want to display it, retrieve it via the endpoint POST products/setproducts/preview. What this means for existing integrations is described at the end of this chapter in the section The set price is no longer stored.products//setproducts
Returns a list of child products if the product withid=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
Response (parent product)
Response (set child product)
Error codes
POST products//setproducts/assign
Products from the request body are assigned to the set of the product withid=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
Request body
Response
Error codes
POST products//setproducts/update/
Data of the product withid=childProductId in the set of the product with id=parentProductId is updated.
For this query, write permissions on product data are required.
Example
Request body
Response
Error codes
POST products/setproducts/preview
This endpoint calculates the price of a set product from the provided values and returns the result. It stores nothing. This allows the set price to be displayed already during editing, that is before the product is saved. Two values are calculated.setPrice is the sum of the price of the main product and the prices of all sub-products with usePrice. setOrgPrice is the sum of the price of the main product and the prices of all sub-products, and serves as a reference price. The prices are resolved as of the current point in time, so active promotional prices flow into both values.
For this query, write permissions on product data are required.
Example
Request body
Response
P1 and 9.99 for P2. setPrice contains the main product and twice P1, so 19.99 plus 9.98. In setOrgPrice, P2 is additionally included because all sub-products flow into it. If all sub-products have usePrice, both values are equal.
Error codes
DELETE products//setproducts/
The product withid=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
Response
Error codes
The set price is no longer stored
The set price is no longer a stored value; it is calculated on demand. The implicit recalculations when creating, updating, and deleting products, in the bulk endpoints, and in the product import have been removed. For clients, this means two things. First, no endpoint delivers a stored set price any longer. Second, a client that wants to display the set price must have it calculated via the endpoint POST products/setproducts/preview.In the shop, the set price continues to be calculated on every page load. The fields on the template object have changed for this;
setPrice and the associated fields are now only available on set products. What this means for existing templates is described in the section Changes to existing templates.Removed fields
Additional references
- API reference image converter
- API reference categories
- API reference configuration
- API reference meta data
- API reference SEO URLs
- content - catalog (categories & products)
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 thecontent.customProductField node must be used. → content - catalog (categories & products)
There you can create individual fields with type, search relevance, mandatory status and variant properties. As soon as a field has been configured there, it is automatically available in the product API afterwards, for example in GET products or POST products.