/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
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, 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
Response
Filter fields
All product data fields,inCategory, notInCategory, inSetProduct, notInSetProduct
Sort fields
All product data fieldsOther parameters
from
Error codes
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
Response
Error codes
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
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 (e.g.11-2518).
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
PUT products/{productId}
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
Error codes
DELETE products/{productId}
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 (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
Response
Error codes
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, 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/{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 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/{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, 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 (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 underselection.
To use this endpoint, the corresponding permissions to read product variants are required.
Example
Response
Error codes
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
Response
Error codes
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
Request body
Response
Error codes
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 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/{productId}/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/{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
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 (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
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/{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
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/{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
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 (e.g.amountis not a Number type) are skipped.
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/{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. 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/{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. 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/{productId}/variants/{variantId}/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/{productId}/variants/{variantId}/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.products/{parentProductId}/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/{parentProductId}/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/{parentProductId}/setproducts/update/{childProductId}
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
PUT products/{childProductId}/setproducts/recalculate
The prices of products belonging to the set of the product withid=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
Response
Error codes
DELETE products/{parentProductId}/setproducts/{childProductId}
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
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 (e.g. in GET products or POST products).