Extended Fields


Some of the product data available in the catalog is very rarely used in the context of rendering cross-selling widgets for the final customers containing recommended products. For this reason, the fields included in the response of a GET /v1/recommendations request is kept to a minimum, making the data modeling simpler and improving performance and response time.

However, some clients, mainly when consuming the data from their backends, may have different data needs because of a number of reasons. For this use-case, the access to extended response fields is made available.

What are Extended Fields

The product data included in the response of

GET /products/:sku

that is not present in the default response of

GET /v1/recommendations

are considered extended fields. These fields are usually optional and may or may not exist for a certain product.

Some examples are:

  • taxes
  • gtin.ean
  • gtin.isbn
  • specs.weight
  • specs.width
  • specs.height
  • specs.length
  • delivery.package.weight
  • delivery.package.width
  • delivery.package.height
  • delivery.package.length
  • vendor.address.support.email

How To Use Extended Fields

In order to receive extended fields in the response of GET /v1/recommendations, the additional query parameter extended=... must be passed together with the usual query parameters. The extended parameter should contain desired optional fields to include in the response’s product model. It can be used in two different ways:

  • the field extended=the.field.name can be repeated multiple times, once per additional extended field. For example: GET /v1/recommendations?seller=my-awesome-shop&country=de&lang=de&extended=taxes&extended=gtin.ean
  • the field extended=... also supports a comma-separated list of fields to be included, in which case it can be passed a single time. Example: GET /v1/recommendations?seller=my-awesome-shop&country=de&lang=de&extended=taxes,gtin.ean,delivery.package.weight

In case the extended parameter is passed, the requested additional fields will be included in the response if they are available. Products without the requested fields will still appear in the provided list of recommendations.

Making Extended Fields Required

In case the requested extended fields are always required, the parameter extendedRequired=true may be passed, which will cause any product not containing the requested extended fields to not be included in the final response.

Using this parameter is, however, not recommended. Any non-compliant products are filtered in a final post-processing step, which means that it can greatly reduce the number and quality of the recommendations, potentially leading to a much greater number responses with an empty set of recommendations, even if eligible products are still available in the platform.