Category Page

Slider #

Category pages are used when a customer is looking for a particular type of product, but not a specific product such as t-shirts, sofas or running shoes. If they had a specific product in mind, they most likely would have looked for it first using the search function.

Categories tend to have many products, so it can be hard to navigate them but many customers are looking for the same few products in the categories. These select products tend to be the same for each customer, so they will likely be the best-sellers. This is because best-sellers offer the customer a sense of security - if the product was popular amongst others there is some proof of value.

By placing these items at the top of the category page as a group of recommendations, it makes it much easier for your customers to navigate. It is likely that these products will pique new customers’ interests and therefore increase the chances for conversion.

Full category page #

Clerk can be used to render all results on a category page, allowing for smart sorting of results, and using Merchandising for a high degree of control over which products are prioritised.

This article describes the use of our API and Clerk.js library as two different ways of handling this rendering.

API endpoints #

Our category recommendations endpoints work exactly the same as our search page endpoint. The only difference is that these endpoints rely on a category ID rather than a search query.

Due to this, they can be used to render all products on category pages by replacing any existing webshop logic for fetching products, with Clerks API. If using a serverside API setup, you can usually keep the existing styling by simply getting the product data from Clerk, while rendering the visuals through the webshops code.

These are the two available endpoints:

• recommendations/category/popular
  (Ranked by best selling items - changes occassionally)
• recommendations/category/trending
  (Ranked by products that are trending in sales - changes often)

The best endpoint to use depends on the type of business.

Many fashion stores with inventory that changes often, generally gets the most out of trending products. Stores with catalogues where customers tend to purchase the same items multiple times, like supplements or food stores, should generally use bestsellers.

API endpoint parameters #

Here is a breakdown of what each argument does when making a call to a category endpoint

• key: The public key for the store
• limit: The amount of products to return
• category: The ID of the category currently browsed
• offset: The index to start the result set from. Used with limit for pagination.
• orderby: An attribute to sort the results on. If not sent, Clerk will order by best selling items
• order: Can be either asc or desc. Sorts the products in ascending or descending order
• attributes: A list of attributes that Clerk should return. Useful for speedy setups where all product data is returned from Clerk. If not set, Clerk only returns product IDs
• filter: A string that configures Clerk to only return a subset of products. Used with existing filters on the page or Clerks facets to allow customers to narrow down results
• facets: A list of attributes to be returned as product options that can then be converted to a filter when a visitor selects it
• labels: The label(s) associated with the category page. Used for identifying performance in my.clerk.io
• visitor: The visitor ID of the current visitor browsing

Filtering results #

• When sending facets in the request, Clerk will return a list of the possible filter options for that result set. E.g. if the cheapest product in the category is €10 and the most expensive one is €500, the lowest price bucket could be €10-50, and the highest €450+ or similar. One category might have 10 different brands and another only 3 in the facets.
• When a visitor selects an option, it should be converted into a filter that is sent in the next API call. E.g. filter=’(price > 10 and price < 100) and brand=”Swarovski"'
• We recommend creating a graphical interface based on Clerks facets and listing them as selectable options as this automatically keeps track of which options are available in each category.
• It can also be done using an existing filter GUI, as long as the visitors choices can be converted to a filter string
• Read more about filters here

Paginating results #

• The limit and offset parameters are used together for pagination
• limit controls the amount of products to return for each call
• offset controls the starting point in the full list of results
• The first call should have offset: 0, and each consecutive call offset: offset + limit
  • Page 1: limit: 60, offset: 0
  • Page 2: limit: 60, offset: 60
  • Page 3: limit: 60, offset: 120
  • … and so on
• The count key from the API response contains the total amount of products in the category, regardless of limit. It can be used to calculate the amount of pages by dividing count with limit and rounding up. E.g: pages = ceil(count / limit)

Full API request & response example #

Here is a full example of a call and response to display products on a category.

It’s configured display:

• Products from the category with ID 13
• 50 products on the second page using limit and offset of 50
• Products with the type “Star Wars” using filters
• Ordered by price low-high using orderby price with ascending order
• Facets for the price and category

// Request
curl --request POST \
     --url 'https://api.clerk.io/v2/recommendations/category/popular' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
     -d '{"key": "Ipkv9tKfxRdpLv3mpMhqxfWGNdqugE0c",
          "limit": 50,
          "category": 13,
          "offset": 50,
          "orderby": "price",
          "order": "asc",
          "attributes": ["id","name","image","price", "url"],
          "filter": "type = \"Star Wars\"",
          "facets": ["price", "category"]
          "labels": ["Category Page Grid - Popular"],
          "visitor": "xfgu47fd2"
        }'

// Response
{
  "status": "ok",
  "result": [
    27988,
    25629,
    22482,
    26994,
    27001,
    28098,
    22484,
    25623,
    27746,
    28097
  ],
  "count": 11,
  "facets": {
    "categories": [
      {
        "type": "unit",
        "name": "Home Accessories",
        "value": 81,
        "count": 1
      },
      {
        "type": "unit",
        "name": "Swarovski",
        "value": 3436,
        "count": 5
      },
      {
        "type": "unit",
        "name": "Home Accessories",
        "value": 3418,
        "count": 5
      }
    ],
    "price": [
      {
        "type": "range",
        "name": "50 - 99",
        "min": 50,
        "max": 99.99,
        "count": 1
      },
      {
        "type": "range",
        "name": "100 - 149",
        "min": 100,
        "max": 149.99,
        "count": 3
      },
      {
        "type": "range",
        "name": "200 - 249",
        "min": 200,
        "max": 249.99,
        "count": 1
      },
      {
        "type": "range",
        "name": "300 <",
        "min": 299.99,
        "max": 383,
        "count": 6
      }
    ]
  },
  "product_data": [
    {
      "id": 27988,
      "image": "https://warstars.com/images/star_wars_tie_fighter_ornament.jpg",
      "name": "Swarovski Star Wars Tie Fighter Ornament ",
      "price": 76,
      "url": "https://warstars.com/products/star_wars_tie_fighter_ornament"
    },
    {
      "id": 25629,
      "image": "https://warstars.com/images/swarovski_star_wars_mandalorian_the_child.jpg",
      "name": "Swarovski Star Wars Mandalorian, The Child",
      "price": 112.5,
      "url": "https://warstars.com/products/star_wars_mandalorian_the_child"
    },
    {
      "id": 22482,
      "image": "https://warstars.com/images/swarovski_star_wars_master_yoda.jpg",
      "name": "Swarovski Star Wars Master Yoda",
      "price": 131.52,
      "url": "https://warstars.com/products/star_wars_master_yoda"
    },
    {
      "id": 26994,
      "image": "https://warstars.com/images/swarovski_star_wars_ewok_wicket.jpg",
      "name": "Swarovski Star Wars Ewok Wicket",
      "price": 132,
      "url": "https://warstars.com/products/star_wars_ewok_wicket"
    },
    {
      "id": 27001,
      "image": "https://warstars.com/images/swarovski_star_wars_han_solo.jpg",
      "name": "Swarovski Star Wars Han Solo",
      "price": 212.5,
      "url": "https://warstars.com/products/star_wars_han_solo"
    },
    {
      "id": 28098,
      "image": "https://warstars.com/images/swarovski_star_wars_boba_fett.jpg",
      "name": "Swarovski Disney Star Wars Boba Fett",
      "price": 300,
      "url": "https://warstars.com/products/star_wars_boba_fett"
    },
    {
      "id": 22484,
      "image": "https://warstars.com/images/swarovski_star_wars_darth_vader.jpg",
      "name": "Swarovski Star Wars Darth Vader",
      "price": 320,
      "url": "https://warstars.com/products/star_wars_darth_vader"
    },
    {
      "id": 25623,
      "image": "https://warstars.com/images/swarovski_star_wars_x_wing_starfighter.jpg",
      "name": "Swarovski Star Wars X-Wing Starfighter",
      "price": 320,
      "url": "https://warstars.com/products/star_wars_x_wing_starfighter"
    },
    {
      "id": 27746,
      "image": "https://warstars.com/images/swarovski_star_wars_chewbacca.jpg",
      "name": "Swarovski Star Wars Chewbacca",
      "price": 340,
      "url": "https://warstars.com/products/star_wars_chewbacca"
    },
    {
      "id": 28097,
      "image": "https://warstars.com/images/swarovski_star_wars_obi_wan_kenobi.jpg",
      "name": "Swarovski Disney Star Wars Obi-Wan Kenobi",
      "price": 350,
      "url": "https://warstars.com/products/star_wars_obi_wan_kenobi"
    }
  ]
}

Using Clerk.js #

Clerk.js is a library that makes it easy to call Clerks API, apply tracking and handling styling.

• The setup works very similarly, although API calls are done from the frontend, using HTML snippets
• By including the Clerk.js script in your header, you can use snippets directly in your frontend
• If you use any of extensions or plugins (e.g. for Magento2 or WooCommerce), Clerk.js will likely already be included
• Clerk.js scans the website for any snippets with the class clerk, and makes API calls using the data- parameters
• Styling can be done with the Liquid templating language, inside the snippet
• Clerk.js can handle pagination without extra coding, by loading more results on the page at the click of a button, using this function: Clerk('content', '#SNIPPET_ID', 'more', LIMIT);
• Facets HTML is generated by configuring the snippet with the facets, their translations and a target HTML block to insert them in. Read more about Clerk.js facets here

Full snippet example:

<div id="clerk-category-filters"></div>

<span 
  id="clerk-category-products"
  class="clerk" 
  data-category="113"
  data-facets-target="#clerk-category-filters" 
  data-facets-attributes='["price","categories"]'
  data-facets-titles='{"price": "Pricing", "categories": "Collections", "brand": "Vendor"}'
  data-facets-price-prepend="€"
  data-facets-in-url="true"
  data-facets-view-more-text="View More"
  data-facets-searchbox-text="Search for ">
  
  <div class="product-search-result-list">
    {% for product in products %}
      <div class="product">
        <h2 class="product-name">{{ product.name }}</h2> 
        <img src="{{ product.image }}" title="{{ product.name }}" />
        <div class="price">${{ product.price | money }}</div>
        <a href="{{ product.url }}">Buy Now</a>
      </div>
    {% endfor %}
    {% if count > products.length %}
        <div class="clerk-load-more-button" 
             onclick="Clerk('content', '#clerk-category-products', 'more', 60);">
              Show More Results
        </div>
    {% endif %}
  </div>
</span>