Sorting

General

Product sorting in e-commerce is the process of arranging products in a specific order by applying different sorting parameters through our API.

Sorting has different use cases:

1. Shop users may organize products based on their preferences, making it easier for them to find what they want and thus, improving their shopping experience.
2. You can control which products appear first in your store. This may help when you want to clear out specific stock or promote certain items.

In this guide you will learn how to use the sorting features provided by SCAYLE and set up your own custom highly flexible sorting for special occasions.

Sorting in a nutshell

SCAYLE offers three different sorting mechanisms to allow you to sort the products according to your needs:

1. Basic Sorting
2. Smart Sorting
3. Custom Sorting

Basic Sorting is a straightforward sorting based on a single attribute, such as price or recency, allowing you to quickly organize products according to the most relevant factor.

In contrast to that, the Smart Sorting provides a more advanced, purpose-driven sorting that combines and prioritizes multiple attributes. This supports you to tailor the order of the products to specific goals like optimizing clearance or ensuring good availability across all variants for the products being shown to the customer.

In case you want to dig even deeper you can utilize the Custom Sorting. It offers the highest grade of flexibility as it allows you to define a sorting score (sortValue) for each product of your shop, that is completely customizable depending on your needs.

Sorting direction

When sorting the products you may decide to see the results with lower values first (asc) or higher values first (desc).

Basic Sorting

As mentioned before, the Basic Sorting uses a single attribute, such as price or recency, to let you organize products according to the most relevant factor.

Utilizing the Basic Sorting you can sort by:

1. Product ID (default)
2. Price
3. Recency
4. Price Reduction

Smart Sorting

Smart Sorting is a set of predefined sorting options based on frequently needed features of many SCAYLE customers.

The Smart Sorting takes into account different weighted factors to allow you to tailor the order of products according to specific business goals such as stock turnover.

Utilizing Smart Sorting you can sort to optimize for:

1. Clearance Sale
2. New Arrivals Push
3. Balanced Value Offerings
4. High Stock Clearance
5. Luxury Promotion
6. Comprehensive Stock Coverage

Custom Sorting

With the Custom Sorting you are completely flexible in ranking your products depending on your needs.

To set up a custom sorting you need to decide

• the name of the sorting (called sortingKey)
• the products to sort
• the ranking of the products (called sortingValue)
• the attribution of the sorting (general level, shop level, country code level)

You can configure these details manually in the SCAYLE Panel or utilizing the Admin API.

Create or update product sorting

To display products in the frontend in a certain order, you can specify a sorting value (sortValue) for each product to determine the product order.

Product sorting can be created for a particular shop or a shop country (in case a country code is provided). Country-specific sorting overrules shop-specific sorting for the same sortingKey.

Example: Setting products sortings

JavaScriptPHPcURLJava

Copy

let sortings = [
  {
    productId: 1,
    shopKey: "ms",
    sortKey: "default",
    sortValue: 1
  },
  {
    productReferenceKey: "my-reference-key",
    shopKey: "ms",
    sortKey: "default",
    sortValue: 2
  }
]

adminApi.apis.ProductSortings.updateOrCreateProductSortings({}, {requestBody: sortings});

Delete product sorting

You can delete shop-specific sorting by providing a shop key. A country-specific sorting can be deleted by providing a shop key and a country code.

When deleting product sorting you either have to provide a productId or productReferenceKey.

Example: Delete product sortings

JavaScriptPHPcURLJava

Copy

let sortings = [
  {
    productId: 1,
    shopKey: "ms"
  },
  {
    productReferenceKey: "my-reference-key",
    shopKey: "ms",
    sortKey: "default"
  }
]

adminApi.apis.ProductSortings.deleteProductSortings({}, {requestBody: sortings});

Product Sorting Parameters

Storefront API

The Storefront API offers different sorting mechanisms to allow your users to sort the products according to their preferences.

In continuation, we will list some examples on how to use Basic Sorting, Sorting Keys, and multiple Sorting Keys at a time.

Basic Sorting

Sorting by Product ID (default)

If you do not include any sorting parameter in your request, default sorting will be applied. Products will then be sorted by their Product ID in descending order.

Sorting by Price

Sorting identifier: sort=price

• sort=price will sort the products by their price.
• To specify the order, use the sortDir parameter (default desc, highest price first).

TypescriptcURL

Copy

import {APISortOrder, APISortOption} from '@scayle/storefront-api';

// Sort products descending by price (most expensive product first)
const responseAsc = await client.products.query({
  sort: {
    by: APISortOption.Price,
    direction: APISortOrder.Ascending,
  },
});

// Sort products ascending by price (cheapest product first)
const responseDesc = await client.products.query({
  sort: {
    by: APISortOption.Price,
    direction: APISortOrder.Descending,
  },
});

Sorting by Recency

Sorting identifier: sort=new

• sort=new will order the products by when they were first shown in the shop.
• To specify the order, use the sortDir parameter (default desc, most recent date first).

TypescriptcURL

Copy

import {APISortOrder, APISortOption} from '@scayle/storefront-api';

// Sort products descending by their created at date (newer products first)
const responseAsc = await client.products.query({
  sort: {
    by: APISortOption.DateAdded,
    direction: APISortOrder.Ascending,
  },
});

// Sort products ascending by their created at date (older products first)
const responseDesc = await client.products.query({
  sort: {
    by: APISortOption.DateAdded,
    direction: APISortOrder.Descending,
  },
});

Sorting by Price Reduction

Sorting identifier: sort=reduction

• sort=reduction will sort products using their total reduction percentage in either ascending or descending order.
• To specify the order, use the sortDir parameter (default asc, highest discount first).
• This takes into account both regular sale discounts and campaign-specific reductions.

TypescriptcURL

Copy

import {APISortOrder, APISortOption} from '@scayle/storefront-api';

// Sort products descending by reduction percentage (products with the highest reduction first)
const responseAsc = await client.products.query({
  sort: {
    by: APISortOption.Reduction,
    direction: APISortOrder.Ascending,
  },
});

// Sort products ascending by reduction percentage (products with no reduction first)
const responseDesc = await client.products.query({
  sort: {
    by: APISortOption.Reduction,
    direction: APISortOrder.Descending,
  },
});

Smart Sorting

Include the sortingKey query parameter in combination with any of the predefined Smart Sorting Keys, in your request to use Smart Sorting Keys, e.g. sortingKey=scayle:v1:sale. When you use the sortingKey parameter in the request, the sort query parameter will be ignored.

Using Sorting Key and Campaign Key Together:

Smart Sorting efficiently manages scenarios where both a sortingKey and a campaignKey are provided. In these cases, the system integrates the campaign key to ensure that the sorting takes into account campaign prices and reductions tied to price-related Smart Sorting Keys. This ensures alignment between the tenant’s smart sorting preferences and the relevant campaign data.

For an example of how to use both a sortingKey and a campaignKey in the same request, refer to the # Smart Sorting Key in Combination with Campaign Key example.

Handling Products Without an Active or Expired Campaign:

If a product does not have an active campaign, or if the campaign has expired, the system will automatically fallback to the product's default (non-campaign) price, labeled as @no_campaign.

Clearance Sale

Sorting Key: scayle:v1:sale

The Clearance Sale sorting:

• Promotes items with the highest discount percentages to quickly clear out older inventory.
• Focuses on items that have been in the shop for a longer time to accelerate their sale.
• Applies weight to items with high stock levels, ensuring that heavily discounted items with large quantities are prioritized.

TypescriptcURL

Copy

import {APISortOrder, APISortOption} from '@scayle/storefront-api';

// Sort products in descending order by `scayle:v1:sale`
const responseDesc = await client.products.query({
  sort: {
    sortingKey: "scayle:v1:sale",
    direction: APISortOrder.Descending,
  },
});

New Arrivals Push

Sorting Key: scayle:v1:new-arrivals

The New Arrivals Push sorting:

• Highlights the latest inventory, helping businesses promote their most recent products.
• Applies some weight to items with high variant availability to ensure these products are prominently displayed.
• Adds a small emphasis on the original price to subtly guide customers toward higher-value new arrivals, enhancing perceived value.

TypescriptcURL

Copy

import {APISortOrder, APISortOption} from '@scayle/storefront-api';

// Sort products in descending order by `scayle:v1:new-arrivals`
const responseDesc = await client.products.query({
  sort: {
    sortingKey: "scayle:v1:new-arrivals",
    direction: APISortOrder.Descending,
  },
});

Balanced Value Offerings

Sorting Key: scayle:v1:recommended

The Balanced Value Offerings sorting:

• Prioritizes offering customers the best absolute discounts.
• Ensures sufficient variant availability to meet customer demand.
• Applies some weight to recency to keep the product offerings fresh.
• Lightly considers the original price to maintain a balance between value and product turnover.

TypescriptcURL

Copy

import {APISortOrder, APISortOption} from '@scayle/storefront-api';

// Sort products in descending order by `scayle:v1:recommended`
const responseDesc = await client.products.query({
  sort: {
    sortingKey: "scayle:v1:recommended",
    direction: APISortOrder.Descending,
  },
});

High Stock Clearance

Sorting Key: scayle:v1:high-stock

The High Stock Clearance sorting:

• Is ideal for clearing out overstocked items.
• Places the highest weight on stock levels to move inventory quickly.
• Applies significant weight to discount value to attract bargain hunters.
• Includes some weight on recency to ensure newly stocked items also receive priority.

TypescriptcURL

Copy

import {APISortOrder, APISortOption} from '@scayle/storefront-api';

// Sort products in descending order by `scayle:v1:high-stock`
const responseDesc = await client.products.query({
  sort: {
    sortingKey: "scayle:v1:high-stock",
    direction: APISortOrder.Descending,
  },
});

Luxury Promotion

Sorting Key: scayle:v1:price-insensitive

The Luxury Promotion sorting:

• Aims at highlighting high-value or luxury items.
• Prioritizes the original price to promote more expensive products and potentially increase average transaction values.
• Applies weight to recency to give prominence to new luxury items.
• Considers the discount percentage to attract attention to luxury items that are on sale.

TypescriptcURL

Copy

import {APISortOrder, APISortOption} from '@scayle/storefront-api';

// Sort products in descending order by `scayle:v1:price-insensitive`
const responseDesc = await client.products.query({
  sort: {
    sortingKey: "scayle:v1:price-insensitive",
    direction: APISortOrder.Descending,
  },
});

Comprehensive Stock Coverage

Sorting Key: scayle:v1:stock

The Comprehensive Stock Coverage sorting:

• Ensures customers see products with a broad range of available variants and ample stock.
• Prioritizes well-stocked products across multiple sizes to reduce the likelihood of out-of-stock situations.
• Includes discount value to highlight items offering a good deal.
• Appeals to customers seeking a balance between availability and savings.

TypescriptcURL

Copy

import {APISortOrder, APISortOption} from '@scayle/storefront-api';

// Sort products in descending order by `scayle:v1:stock`
const responseDesc = await client.products.query({
  sort: {
    sortingKey: "scayle:v1:stock",
    direction: APISortOrder.Descending,
  },
});

Smart Sorting Key in Combination with Campaign Key

Sorting Key: scayle:v1:sale

Campaign Key: sapiCampaignKey

The Clearance Sale sorting with campaign prioritization operates as follows:

• Prioritizes items offering the highest campaign discount percentages, driving the quick liquidation of older inventory and incentivizing customer purchases.
• Focuses on items that have been in stock for a longer duration, accelerating the clearance of slow-moving products while aligning with campaign strategies.
• Assigns higher priority to items with substantial stock levels, ensuring that heavily discounted items with large quantities are prominently featured, optimizing both clearance objectives and campaign impact.

TypescriptcURL

Copy

import {APISortOrder, APISortOption} from '@scayle/storefront-api';

// Sort products in descending order by `scayle:v1:sale` with a campaign `sapiCampaignKey`
const responseDesc = await client.products.query({
  campaignKey: "sapiCampaignKey",
  sort: {
    sortingKey: "scayle:v1:sale",
    direction: APISortOrder.Descending,
  },
});

Custom Sorting

You can also sort products using your own specified sorting keys using the sortingKey parameter.

TypescriptcURL

Copy

import {APISortOrder} from '@scayle/storefront-api';

// Request the products in descending order using your 'default' sorting key
const responseAsc = await client.products.query({
  sort: {
    // This value is what you specify when you upload your custom sorting into SCAYLE
    sortingKey: 'my-custom-key',
    direction: APISortOrder.Ascending,
  },
});

// Request the products in ascending order using your 'default' sorting key
const responseDesc = await client.products.query({
  sort: {
    // This value is what you specify when you upload your custom sorting into SCAYLE
    sortingKey: 'my-custom-key',
    direction: APISortOrder.Descending,
  },
});

Combined Sorting

It is possible to use multiple sorting keys at a time. If multiple sorting keys are used at the same time, all products are ordered by Sorting Key 1 first, then all products with the same value for Sorting Key 1 are ordered by Sorting Key 2.

There are different use cases where having multiple sorting keys can be advantageous, such as:

Boosting of certain products

To give an example of boosting certain products: You might want to always have your high priority products which have a lot of business impact on top of the page, so you can attach a custom sorting key priority with a value of 1 to all items you consider high priority. Additionally, you may want the products to be sorted by a discount in descending order.

Then, you apply the following query parameter: sortingKey=priority,scayle:v1:sale and define them to be sorted in descending order.

This will sort all the bestsellers on top, and sort these shirts using the scayle:v1:sale sorting.
All other products will then show up below and also be sorted using scayle:v1:sale.

TypescriptcURL

Copy

import {APISortOrder, APISortOption} from '@scayle/storefront-api';

// Sort products in descending order by both `scayle:v1:high-stock` and `scayle:v1:new-arrivals`
const responseDesc = await client.products.query({
  sort: {
      sortingKey: "shirts,scayle:v1:new-arrivals",
      direction: APISortOrder.Descending,
    },
});

Assortment Clusters

Another use-case is to cluster your assortment into high level clusters and then sorting these Clusters using a Smart Sorting Key. This allows you to still control the rough position of each product but with a much more simple sorting logic on your end.

One example could be to cluster your products per season, so you can be sure that summer products will be on top during the summer, and vice versa during the winter.
You would define a custom sorting key called season where the current seasonal products would have the score of 1. All other products should have a score of 0 assigned.

TypescriptcURL

Copy

import {APISortOrder, APISortOption} from '@scayle/storefront-api';

// Sort products in descending order by both `season` and `scayle:v1:recommended`
const responseDesc = await client.products.query({
  sort: {
    sortingKey: "season,scayle:v1:recommended",
    direction: APISortOrder.Descending,
  },
});