Product list response templates¶

Using templates is a way to optimize Elevate's query responses to only include data that is relevant for rendering your site. This can significantly reduce response sizes, resulting in a faster and more memory-efficient site with improved user experience and potentially lower hosting costs.

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 their own endpoint in the Admin Api. You can import up to 5 different templates. The PUT endpoint replaces all existing templates with your import, while the POST endpoint will only add, update or remove the templates listed in the 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 in a JSON format. They consist of an id, product level settings and variant level settings. The template format is based on the product data in Storefront query responses. They have a primary (first) product, which is the one the product card belongs to, and a remainder (rest) consisting of the other products within the product group. You can either use separate rules for the first and rest of the products listed in the response, or the same rules for all of them. The same goes for variant data on each 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.

As mentioned above, 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 the 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 think that 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.

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 (this includes any typed custom fields). In order to include specific typed custom attributes use the following prefixes: custom.json., custom.length., and custom.number.. Note that custom.json.* etc. is not supported.

Using templates¶

When you have imported a template, you can start applying it in Storefront queries by including templateId as a query parameter with the template ID to use. 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
• Autocomplete
• Cart page
• Landing page
• Product page
• Search page

Template examples¶

{
  "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"
            ]
          }
        }
      }
    }
  }
}

{
  "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
      }
    }
  }
}