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.

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. & 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
      }
    }
  }
}