Skip to content

Product list response templates

By default, when making a request to Elevate's Storefront API you will receive a large response object with a lot of information on each product group, product and variant returned. While this allows Elevate to cater for many different use cases, if your integration doesn't need all this information it becomes wasteful as you spend bandwidth, memory and processing power for things you don't use. This is especially true for product groups with many products and variants, as a lot of data may be repeated.

By defining a template, you can tell Elevate which fields you wish to include in the response, and whether to include them for all products and variants in a product group or only for the primary product and the first listed variant.

Additionally, by using a template, you no longer have to provide the presentCustom query parameter to specify which custom attributes to include in each request.

Importing templates

Templates are imported via its own endpoint in the Admin Api. You can import up to 5 different templates. Note that a template import will replace all existing templates: if you only wish to add or update a single template without removing the rest, make a template export and include those templates in your import.

The template import uses dangerous import protection, so if your import were to remove an existing template it will fail and you will be asked to redo the import with the header flag force=true.

Template format

Templates are imported on a JSON format consisting of an id, product level settings and variant level settings. You can choose to either define what data to include separately in the first and the rest of the products, or define what to include in all of them. Same with variant data on a product.

Consider the example below:

{
  "template1": {
    "products": {
      "first": {
        "fields": [
          "title", "link", "sellingPrice"
        ],
        "variants": {
          "all": {
            "fields": [
              "label", "custom.campaign"
            ]
          }
        }
      },
      "rest": {
        "fields": [
          "link", "swatch"
        ],
        "maxVariants": 0
      }
    }
  },
  "template2": {
    ...
  }
}

This example contains two templates with the IDs template1 and template2 respectively. While the content of template2 has been omitted for brevity, the first template is defined as follows:

  • For the first product in each group, return the title, link and sellingPrice
  • For all its variants, return their label and custom campaign attribute.
  • For other products in the group, return only the link and swatch fields
  • Include none of their variants.

On product level, the first product refers to the main product to be rendered while the other products are alternatives or swatches (see the modeling guide).

On variant level, there exists no "primary" variant. Therefore, it usually makes no sense to use first and rest on variant level as whichever variant is first in the response will be arbitrary. If you feel like there are variant fields that you don't need repeated for each variant, consider whether it's possible to raise them to the product level instead.

By using maxVariants you can specify how many variants should be included (at most) on each product. If you don't display sizes on product cards you might want to set this to 0 for the first and/or the rest of the products, as in the example. The variants block may be omitted if maxVariants is 0.

Tip

It is generally recommended to use first and rest on product level and all on variant level. Exclude any fields you don't need, especially in the rest group as most attributes are only relevant for the main product.

Available fields

You can include any field specified in the api response. See the Storefront specification for the full list. Custom attributes should be prefixed with custom. Additionally, the special syntax custom.* can be used to include all custom fields on a product or variant.

Using templates

When you have imported a template you can start applying it in all Storefront queries by including the templateId query parameter. It can be applied to all requests that return product listings and will apply to all lists returned (e.g. applying to both a page's primary list and recommendation lists). Note that on the product page, the template only applies to lists on the page and not for the main product the page belongs to: all of its fields will still be returned.

The following requests support templates: - Add to cart popup - Auto complete - Cart page - Landing page - Product page - Search page

Template examples

The default when no template is specified, with no custom attributes
{
  "default": {
    "products": {
      "all": {
        "fields": [
          "swatch",
          "inStock",
          "depth",
          "height",
          "length",
          "width",
          "volume",
          "weight",
          "listPrice",
          "sellingPrice",
          "imageInfo",
          "badges",
          "brand",
          "title",
          "name",
          "series",
          "link",
          "rating"
        ],
        "variants": {
          "all": {
            "fields": [
              "size",
              "label",
              "inStock",
              "stockNumber",
              "availability",
              "prices",
              "link",
              "listPrice",
              "sellingPrice",
              "width",
              "height",
              "length",
              "depth",
              "volume",
              "weight"
            ]
          }
        }
      }
    }
  }
}
Limit information on swatches and variants, with all custom attributes
{
  "template_id": {
    "products": {
      "first": {
        "fields": [
          "swatch",
          "inStock",
          "listPrice",
          "sellingPrice",
          "imageInfo",
          "brand",
          "title",
          "link",
          "custom.*"
        ],
        "variants": {
          "all": {
            "fields": [
              "label",
              "inStock",
              "sellingPrice",
              "listPrice",
              "custom.*"
            ]
          }
        }
      },
      "rest": {
        "fields": [
          "inStock",
          "link"
        ],
        "maxVariants": 0
      }
    }
  }
}
×
Copyright

This online publication is intellectual property of Voyado Lund AB. Its contents can be duplicated in part or whole, provided that a copyright label is visibly located on each copy and the copy is used in conjunction with the product described within this document.

All information found in these documents has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither Voyado Lund AB nor the authors shall be held liable for possible errors or the consequences thereof.

Software and hardware descriptions cited in these documents might be registered trademarks. All trade names are subject to copyright restrictions and may be registered trademarks. Voyado Lund AB essentially adheres to the manufacturer’s spelling. Names of products and trademarks appearing in this document, with or without specific notation, are likewise subject to trademark and trade protection laws and may thus fall under copyright restrictions.

CLOSE