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:

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.
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:

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:

Smart Sorting

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

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:

Custom Sorting

With 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 through the Admin API.

Products without a sortValue for the respective sortingKey are returned after all products that have a sortValue assigned.

Custom Sorting Key Creation

Custom product sortings are created on the global or shop-country level. The following permissions are required in order to maintain custom product sortings:

permission shop__product__custom_sorting__list = to see the overview of configured sortings

permission shop__product__custom_sorting__show = to see the details of the configured sortings

shop__product__custom_sorting__update = to update sortings

shop__product__custom__sorting__create = to create sortings

shop__product__custom_sorting__delete = to delete sortings

If a shop country does not have its own sorting, the sorting configuration from the global shop is used. Creating a new sorting will override the global default.

Create a product sorting:

Navigate to Shops ➜ [Shop] ➜ Products ➜ Sorting ➜ New Sorting.
Click New Sorting.
Enter a Sorting Key. For every sorting, a unique Sorting Key must be defined.
Click Add Products to add several products to the Sorting Key.
Define a Sorting Value for each product. Use the up/down arrows or enter values manually.
When complete, click Save Sorting.

Sorting values will be saved relative to each product ID. The sorting key can be used for the Storefront API endpoints.

Sorting Bulk Import

The bulk import for the product sorting can be found under Settings ➜ Imports & Jobs ➜ Imports ➜ Products ➜ Product Sorting Keys.

To import product sortings, create a CSV file with one row per product and sorting key, and the following column headers:

product_id: the SCAYLE product id, which should get a sorting value.
application_id: the application / shop id for which the sorting should be used.
sort_key: the sorting key for the product sorting.
sort_value: the sorting value (Score) of the product for the sorting key.

For more general information about imports, see the Imports page.

Applying Sorting Keys to a Shop and Its Categories

Basic Sorting

With no sorting applied at all, the default basic sorting by Product ID will be assigned. Products will then be sorted by their Product ID in descending order. If either a basic or a smart sorting is applied to shop categories, the basic sorting will not apply anymore.

Smart Sorting

With the permission shop__product__smart_sorting__edit you can define a default smart sorting on global shop level, which will apply to all categories in all countries of the respective shop. You can also define a default smart sorting on country shop level, which will override default sorting configurations on global shop level and will only apply to the respective shop country.

On shop country category level, you have the possibility to further refine smart sortings category-specific. Find out how to do that here.

Custom Sorting

Custom Sortings can be applied to categories on country category level. Only one smart sorting or one custom sorting or a combination of one of each can be applied to a category. If both, a custom sorting and a smart sorting are defined for a category, products will first be sorted by the custom sorting, if multiple products have the same custom sorting key value, those products will then be sorted by the smart sorting.

For further information on how custom and smart sorting configuration is maintained and inherited on category level, please refer to the Shop Categories Section.

Define Sorting for a Price Campaign

You can assign a product sorting to a price campaign as follows:

Define a sorting key to be used for the shop category via the SCAYLE Panel (see above) or the Admin API.
Define a custom data parameter on Price Campaigns level via the SCAYLE Panel.
Add the sorting key for the price campaign in the custom data parameter.
The parameter will be shown as part of the price campaign creation (see image below).

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.

Updating shop-specific sorting doesn't affect existing country-specific sorting.

Example: Setting Product-Sortings

This method accepts a list of maximum 1,000 sorting at a time.

In case there are multi-languages shop countries defined within a shop, the product sorting will be created or updated for all identified shop countries. Please see more details about shop countries limitation here.

Parameter	Details
`productId`	Integer SCAYLE's internal product identifier.
`productReferenceKey`	String Tenant provided product identifier.
`shopKey`	String A key that uniquely identifies the shop within the tenant's ecosystem.
`countryCode`	String ISO 3166 alpha 2 country code.
`sortKey`	String The custom sorting key.
`sortValue`	Integer The value used for sorting.

When updating or creating product sorting, you either have to provide a productId or productReferenceKey.

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

This method accepts a list of a maximum 1,000 sortings at a time.

Please note that it can take some hours until the deleted sorting is reflected in the Storefront API.

Product Sorting Parameters

Parameter	Details
`productId`	Integer SCAYLE's internal product identifier.
`productReferenceKey`	String Tenant provided product identifier.
`shopKey`	String A key that uniquely identifies the shop within the tenant's ecosystem.
`sortKey`	String The custom sorting key.

Storefront API

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

When using the filters[term] parameter, we don't recommend specifying any sorting parameter.

We then sort the products by how well the product matches the search term, which will generally be a better sorting in these cases.

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

Default Sorting

Default sorting will be applied if no sorting parameters are included in your request.

You can set a default sorting key or a combination of default sorting keys in the SCAYLE Panel. If no default sorting is defined, the products will be sorted by ID in descending order.

Basic Sorting

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).

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).

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.

Smart Sorting

To use the Smart Sorting Keys, you can:

Set a Smart Sorting Key as the default sorting for a global shop, country shop or category in the SCAYLE Panel or
include the sortingKey query parameter in combination with any of the predefined Smart Sorting Keys in your request

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 fall back to the product's default (non-campaign) price, labeled as @no_campaign.

Smart Sorting is intended to be used with the sorting direction desc returning the most relevant results first.

Sales Push

Sorting Key: scayle:v1:sales-push

The Sales Push sorting:

Promotes items with the highest discount percentages to quickly clear out older inventory.
Prioritizes oldest products to get them out of the stock.
Balances promotion of high-margin products with discounted items.
Considers current inventory levels to promote available products.

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

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

New Arrivals Push

Sorting Key: scayle:v1:new-arrivals

The New Arrivals Push sorting:

Prioritize products based on how recently they were added or published, with newer items ranked higher.
Applies some weight to items with high variant availability to ensure these products are prominently displayed.
Incorporate sales data to slightly favor products with better historical sales performance.

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:balanced-offerings

The Balanced Value Offerings sorting:

Applies some weight to recency to keep the product offerings fresh.
Ensures sufficient variant availability to meet customer demand.
Highlight products with significant discounts.
Use sales data to highlight popular items while considering original prices for balance.

Inventory Optimization

Sorting Key: scayle:v1:inventory-optimization

The Inventory optimization sorting:

Prioritize products with higher stock levels to optimize inventory turnover.
Consider revenue contribution to promote high-performing products.
Boost products offering greater absolute discount values.
Highlight products with attractive discount percentages.

Luxury Promotion

Sorting Key: scayle:v1:luxury-promotion

The Luxury Promotion sorting:

Prioritize original price to highlight high-value luxury items.
Apply weight to discounts to draw attention to luxury items on sale.
Consider revenue contribution to promote top-performing luxury products.
Slight preference for recently added or published luxury items to favor products with more variant options available.

Comprehensive Stock Coverage

Sorting Key: scayle:v1:stock-coverage

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.
Promote products with strong sales performance.
Includes discount value to highlight items offering a good deal.

Topseller

Sorting Key: scayle:v1:topseller

The Topseller sorting:

Strongly prioritize products with high sales performance.
Prioritizes well-stocked products across multiple sizes to reduce the likelihood of out-of-stock situations.
Boost products contributing significantly to revenue.

Revenue Maximization

Sorting Key: scayle:v1:revenue-max

The Revenue Maximization sorting:

Strongly prioritize products with the highest revenue contribution.
Prioritizes well-stocked products across multiple sizes to reduce the likelihood of out-of-stock situations.
Consider sales performance to highlight popular products.

Recently Popular

Sorting Key: scayle:v1:recently-popular

The Recently Popular sorting:

Strongly favor products with high recent sales performance.
Applies some weight to recency to keep the product offerings fresh.
Boost products contributing significantly to recent revenue.

Smart Sorting Key in Combination with Campaign Key

Sorting Key: scayle:v1:sales-push

Campaign Key: sapiCampaignKey

The Sales Push sorting with campaign prioritization operates as follows:

Prioritizes items with the highest campaign discount percentages to drive customer purchases and enhance sales-push efforts for featured products.
Focuses on items that have been in stock longer, leveraging sales-push campaigns to accelerate the movement of slower-selling inventory.
Assigns higher priority to items with substantial stock levels, ensuring prominently featured discounts align with sales-push objectives for maximum impact.

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

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

Custom Sorting

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

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:sales-push 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:sales-push sorting.
All other products will then show up below and also be sorted using scayle:v1:sales-push.

Sorting by custom key "Priority" and Smart Sorting Key "`sales-push`" (Sales push)

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.