Storefront API Catalog - WEBSALE Dokumentation

The Catalog API provides the central information for products and categories and thus forms the basis for product detail pages, category pages, and navigation elements. It delivers standard attributes (e.g. name, description, price), complemented by custom product and category attributes as well as SEO information such as meta data and speaking URLs. In addition, category structures (hierarchies, subcategories, links) can be retrieved, as well as individual products/categories or product lists in the context of a category. Functions for search results and category pages — such as filters, sorting, paging, or the number of products per page — are not provided via the Catalog API. These tasks are handled by the separate module WEBSALE search and the integration can be done either via the corresponding WEBSALE WebComponents or the Search API.

Supported methods

List of all supported methods.

Command	Endpoints	GET	PUT	POST	DELETE
Retrieve product details for an item	`catalog/product/load`
Retrieve variant information for a product	`catalog/product/variantInfo`
Load all categories in which a specific product appears	`catalog/product/categoryMembership`
Load category paths in which a specific product appears	`catalog/product/categoryMembershipPaths`
Load list of all available product fields	`catalog/product/fields`
Load list of all available user-defined product fields	`catalog/product/customFields`
Load details of a category	`catalog/category/load`
Load subcategory of a category	`catalog/category/loadChildren`
Load complete path up to the category	`catalog/category/path`
Load product list for a specified category	`catalog/category/products`
Load list of all available category fields	`catalog/category/fields`
Load list of all user-defined category fields	`catalog/category/customFields`

Methods for products

These methods provide product information for the storefront. The detail data of an individual item (including configurable product fields and, if applicable, custom fields) is loaded, complemented by variant information (e.g. selectable attributes and associated variant items). In addition, all categories and category paths in which a product is listed can be determined, for example for breadcrumbs, tile teasers, or filters. Through dedicated endpoints, the complete list of all standardized and user-defined product fields is also returned. This means that search, filter, detail pages, and integrations (e.g. ERP/PIM connections) can dynamically build on the data structure actually configured in the shop.

GET catalog/product/load

The following call loads the product details for an item. Which fields appear in the response can be controlled in the catalog configuration: storefrontApi - Storefront API. This can be used to display a product detail page or to load product info specifically on demand. Example call that loads the product details for the product with the ID 146-78608:

GET https://<your-shop>.de/api/v1/catalog/product/load?productId=146-78608

Parameter overview

Parameter	Type	Description
`productId`	string	Required field* Product ID of the item.
`itemNumber`	string	Required field* Product number (SKU) of the item.
`customNumber`	string	Required field* A freely assigned item identifier (e.g. ERP ID or marketing number).

*Exactly one of the three parameters must be passed.

Example response

{
  "custom": {
    "image": {},
    "setOrgPrice": 0.0
  },
  "id": "146-78608",
  "name": "Plushie",
  "price": 6.7,
  "setOrgPrice": 0.0
}

GET catalog/product/loadList

The following call loads the product details for multiple items. Which fields appear in the response can be controlled in the catalog configuration: storefrontApi - Storefront API. This can be used to efficiently display multiple products on a category page. Example call that loads the product details for the products with the ID 146-78608 and 147-3720:

GET https://<your-shop>.de/api/v1/catalog/product/loadList?productId=146-78608&productId=147-3720

Parameter overview

Parameter	Type	Description
`productId`	string	Required field* Product ID of the item.
`itemNumber`	string	Required field* Product number (SKU) of the item.
`customNumber`	string	Required field* A freely assigned item identifier (e.g. ERP ID or marketing number).

*Only parameters of one type (productId, itemNumber, customNumber) can be passed. Any number of parameters of one type can be specified.

Example response

[
  {
    "custom": {
      "image": {},
      "setOrgPrice": 0.0
    },
    "id": "146-78608",
    "name": "Plushie",
    "price": 6.7,
    "setOrgPrice": 0.0
  },
  {
    "custom": {
      "image": {},
      "setOrgPrice": 0.0
    },
    "id": "147-3720",
    "name": "Pen",
    "price": 3.7,
    "setOrgPrice": 0.0
  }
]

GET catalog/product/variantInfo

The following call returns the variant information for a product. It can be used, for example, to build the variant selector on the product page. Example call that loads the variant information for the product with the ID 146-78608:

GET https://<your-shop>.de/api/v1/catalog/product/variantInfo?productId=146-78608

Parameter overview

Parameter	Type	Description
`productId`	string	Required field ID of the product whose variants should be loaded.

Example response

{
  "numVariants": 2,
  "variantAttributes": [
    {
      "name": "Memory",
      "options": [
        {
          "name": "128 GB",
          "resolvedVariant": {
            "base": {
              "base": null,
              "custom": { "image": {}, "setOrgPrice": 0.0 },
              "id": "146-78608",
              "name": "Plushie",
              "price": 6.7,
              "setOrgPrice": 0.0
            },
            "custom": { "image": {}, "setOrgPrice": 0.0 },
            "id": "146-78608.1",
            "name": "Plushie",
            "price": 6.7,
            "setOrgPrice": 0.0
          }
        },
        { "name": "512 GB" }
      ]
    }
  ]
}

GET catalog/product/categoryMembership

The following call returns all categories in which a particular product is currently sorted. It can be used for breadcrumbs or to pre-fill product navigation/filters. Example call that returns all categories in which the product with the ID 147-15732 is sorted:

GET https://<your-shop>.de/api/v1/catalog/product/categoryMemberships?productId=147-15732

Parameter overview

Parameter	Type	Description
`productId`	string	Required field ID of the product whose category memberships should be loaded.

Example response

[
  {
    "custom": { "image": {} },
    "id": "135-98530",
    "name": "Cool things"
  },
  {
    "custom": { "image": {} },
    "id": "104-40827",
    "name": "Sale"
  }
]

GET catalog/product/categoryMembershipPaths

The following call returns all complete category paths (from the root to the target category) in which a particular product appears. It can be used for breadcrumbs, SEO navigation, or the display of alternative paths of a product. Example call that displays the complete category paths for the product with the ID 147-15732:

GET https://<your-shop>.de/api/v1/catalog/product/categoryMembershipPaths?productId=14715732

Example request

{
  "productId": "147-15732"
}

Parameter overview

Parameter	Type	Description
`productId`	string	Required field ID of the product whose category memberships should be loaded.

Example response

{}

GET catalog/product/fields

The following call lists all standard product fields available in the system including their metadata. It can be used to build product pages or to adapt search and filter functions.

GET https://<your-shop>.de/api/v1/catalog/product/fields

Parameter overview

Parameter	Type	Description
—	—	No additional parameters.

Example response

[
  {
    "dataId": "active",
    "label": "",
    "manualEditable": true,
    "name": "active",
    "protectedField": false,
    "required": false,
    "searchBoost": 1,
    "searchable": true,
    "serviceFilter": true,
    "type": "Enumeration"
  },
  {
    "dataId": "descr",
    "label": "",
    "manualEditable": true,
    "name": "descr",
    "protectedField": false,
    "required": false,
    "searchBoost": 2,
    "searchable": true,
    "serviceFilter": false,
    "type": "Text"
  },
  {
    "dataId": "id",
    "label": "",
    "manualEditable": false,
    "name": "id",
    "protectedField": false,
    "required": true,
    "searchBoost": 2,
    "searchable": true,
    "serviceFilter": true,
    "type": "Text"
  },
  {
    "dataId": "itemNumber",
    "label": "",
    "manualEditable": true,
    "name": "itemNumber",
    "protectedField": false,
    "required": true,
    "searchBoost": 2,
    "searchable": true,
    "serviceFilter": true,
    "type": "Text"
  },
  {
    "dataId": "name",
    "label": "",
    "manualEditable": true,
    "name": "name",
    "protectedField": false,
    "required": true,
    "searchBoost": 6,
    "searchable": true,
    "serviceFilter": true,
    "type": "Text"
  },
  {
    "dataId": "price",
    "label": "",
    "manualEditable": true,
    "name": "price",
    "protectedField": false,
    "required": true,
    "searchBoost": 1,
    "searchable": false,
    "serviceFilter": false,
    "type": "Price"
  }
]

GET catalog/product/customFields

The following call lists all user-defined product fields available in the system including their metadata. It can be used to build product pages or to adapt search and filter functions.

GET https://<your-shop>.de/api/v1/catalog/product/customFields

Parameter overview

Parameter	Type	Description
—	—	No additional parameters.

Example response

[
  {
    "dataId": "4682",
    "label": "activityLevel",
    "manualEditable": true,
    "name": "activityLevel",
    "protectedField": false,
    "required": false,
    "searchBoost": 1,
    "searchable": false,
    "serviceFilter": false,
    "type": "Text"
  },
  {
    "dataId": "4683",
    "label": "animalSize",
    "manualEditable": true,
    "name": "animalSize",
    "protectedField": false,
    "required": false,
    "searchBoost": 1,
    "searchable": false,
    "serviceFilter": false,
    "type": "Text"
  },
  {
    "dataId": "4684",
    "label": "animalSpecies",
    "manualEditable": true,
    "name": "animalSpecies",
    "protectedField": false,
    "required": false,
    "searchBoost": 1,
    "searchable": false,
    "serviceFilter": false,
    "type": "Text"
  },
  {
    "dataId": "4685",
    "label": "areaOfApplication",
    "manualEditable": true,
    "name": "areaOfApplication",
    "protectedField": false,
    "required": false,
    "searchBoost": 1,
    "searchable": false,
    "serviceFilter": false,
    "type": "Text"
  }
]

Methods for categories

These methods work with the categories in the catalog: they load the detail data of an individual category, return its direct subcategories, and deliver the complete path from the root to the target category (e.g. for breadcrumbs). In addition, all products of a category can be queried and the category fields available in the system can be read out.

GET catalog/category/load

The following call loads the details of an individual category (e.g. ID, name). It can be used to display category titles, images/content, as well as for navigation or breadcrumb buildup. Example call that displays the details of the category with the ID 135-98530:

GET https://<your-shop>.de/api/v1/catalog/category/load?=categoryId=135-98530

Parameter overview

Parameter	Type	Description
`categoryId`	string	Required field ID of the category to be loaded.

Example response

{
  "custom": { "image": {} },
  "id": "135-98530",
  "name": "Cool things"
}

GET catalog/category/loadChildren

The following call returns the direct subcategories of a category. It can be used to build navigation trees, tile or teaser lists on category pages, as well as for breadcrumb extensions. Example call that returns the direct subcategories of the category with the ID 135-98530:

GET https://<your-shop>.de/api/v1/catalog/category/loadChildren?categoryId=135-98530

Parameter overview

Parameter	Type	Description
`categoryId`	string	Required field ID of the category to be loaded.

Example response

[
  {
    "custom": { "image": {} },
    "id": "100-14213",
    "name": "Clothing"
  }
]

GET catalog/category/path

The following call returns the complete category path from the root to the specified category (including it). It can be used for breadcrumbs, SEO path information, navigation bars, or context displays on category pages. Example call that delivers the complete path of the category with the ID 104-40827:

GET https://<your-shop>.de/api/v1/catalog/category/path?categoryId=104-40827

Parameter overview

Parameter	Type	Description
`categoryId`	string	Required field ID of the category whose path should be loaded.

Example response

[
  { "custom": { "image": {} }, "id": "135-98530", "name": "Cool things" },
  { "custom": { "image": {} }, "id": "100-14213", "name": "Clothing" },
  { "custom": { "image": {} }, "id": "104-40827", "name": "Sale" }
]

GET catalog/category/products

The following call returns the product list for a specified category. It can be used, for example, to populate category listing pages.

GET https://<your-shop>.de/api/v1/catalog/category/products

Example request

{
  "categoryId": "135-98530"
}

Parameter overview

Parameter	Type	Description
`categoryId`	string	Required field ID of the category whose products should be loaded.

Example response

{}

GET catalog/category/fields

The following call returns a list of all available category fields including type information. It can be used for forms, validations, or to display category attributes.

GET https://<your-shop>.de/api/v1/catalog/category/fields

Parameter overview

Parameter	Type	Description
—	—	No additional parameters.

Example response

[
  {
    "dataId": "active",
    "label": "",
    "manualEditable": true,
    "name": "active",
    "required": false,
    "searchable": false,
    "serviceFilter": false,
    "type": "Enumeration"
  },
  {
    "dataId": "descr",
    "label": "",
    "manualEditable": true,
    "name": "descr",
    "required": false,
    "searchable": false,
    "serviceFilter": false,
    "type": "Text"
  },
  {
    "dataId": "hidden",
    "label": "",
    "manualEditable": true,
    "name": "hidden",
    "required": false,
    "searchable": false,
    "serviceFilter": false,
    "type": "Bool"
  },
  {
    "dataId": "id",
    "label": "",
    "manualEditable": false,
    "name": "id",
    "required": true,
    "searchable": false,
    "serviceFilter": false,
    "type": "Text"
  }
]

GET catalog/category/customFields

The following call returns a list of all available user-defined category fields including type information. It can be used for forms, validations, or to display category attributes.

GET https://<your-shop>.de/api/v1/catalog/category/customFields

Parameter overview

Parameter	Type	Description
—	—	No additional parameters.

Example response

[
  {
    "dataId": "4645",
    "label": "alternative template",
    "manualEditable": true,
    "name": "alternativeTemplate",
    "required": false,
    "searchable": false,
    "serviceFilter": false,
    "type": "Text"
  },
  {
    "dataId": "4651",
    "label": "Default sorting",
    "manualEditable": true,
    "name": "defaultSort",
    "required": false,
    "searchable": false,
    "serviceFilter": false,
    "type": "Text"
  },
  {
    "dataId": "4641",
    "label": "Category",
    "manualEditable": true,
    "name": "image",
    "required": false,
    "searchable": false,
    "serviceFilter": false,
    "type": "MultiFormatImage"
  },
  {
    "dataId": "4644",
    "label": "Inherit products to parent categories",
    "manualEditable": false,
    "name": "inheritProductsToParents",
    "required": false,
    "searchable": false,
    "serviceFilter": false,
    "type": "Bool"
  }
]

​Supported methods

​Methods for products

​GET catalog/product/load

​Parameter overview

​Example response

​GET catalog/product/loadList

​Parameter overview

​Example response

​GET catalog/product/variantInfo

​Parameter overview

​Example response

​GET catalog/product/categoryMembership

​Parameter overview

​Example response

​GET catalog/product/categoryMembershipPaths

​Example request

​Parameter overview

​Example response

​GET catalog/product/fields

​Parameter overview

​Example response

​GET catalog/product/customFields

​Parameter overview

​Example response

​Methods for categories

​GET catalog/category/load

​Parameter overview

​Example response

​GET catalog/category/loadChildren

​Parameter overview

​Example response

​GET catalog/category/path

​Parameter overview

​Example response

​GET catalog/category/products

​Example request

​Parameter overview

​Example response

​GET catalog/category/fields

​Parameter overview

​Example response

​GET catalog/category/customFields

​Parameter overview

​Example response

Supported methods

Methods for products

GET catalog/product/load

Parameter overview

Example response

GET catalog/product/loadList

Parameter overview

Example response

GET catalog/product/variantInfo

Parameter overview

Example response

GET catalog/product/categoryMembership

Parameter overview

Example response

GET catalog/product/categoryMembershipPaths

Example request

Parameter overview

Example response

GET catalog/product/fields

Parameter overview

Example response

GET catalog/product/customFields

Parameter overview

Example response

Methods for categories

GET catalog/category/load

Parameter overview

Example response

GET catalog/category/loadChildren

Parameter overview

Example response

GET catalog/category/path

Parameter overview

Example response

GET catalog/category/products

Example request

Parameter overview

Example response

GET catalog/category/fields

Parameter overview

Example response

GET catalog/category/customFields

Parameter overview

Example response