Sorting

General

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

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:

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, Smart Sorting provides a more advanced, purpose-driven sorting that combines and prioritizes multiple attributes. This supports you in tailoring 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, which 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 takes into account different weighted factors to allow you to tailor the order of products according to specific business goals, such as stock turnover.

Under Shops ➜ [Shop] ➜ Products ➜ Sorting ➜ Sorting Methods, SCAYLE provides a set of system Smart Sorting Keys based on frequently needed features of many SCAYLE customers. To access this page, you need the permission shop__product__smart_sorting__list. You can also build your own Custom Smart Sorting Keys from the same weighted factors, called ranking factors.

The following system Smart Sorting Keys are available:

1. Trending
2. Sales Push
3. New Arrivals Push
4. Balanced Value Offerings
5. Inventory Optimization
6. Luxury Promotion
7. Comprehensive Stock Coverage
8. Topseller
9. Revenue Maximization
10. Recently Popular

Setting Up Your Core Variants for Availability Calculation

The following system Smart Sorting Keys take variant availability into account when calculating sorting scores:

• Trending
• New Arrivals Push
• Balanced Value Offerings
• Luxury Promotion
• Comprehensive Stock Coverage
• Topseller
• Revenue Maximization

These Smart Sorting Keys assign a higher score to products that have a higher percentage of their variants in stock.

Since not all variants are equally important to your sales, you have the option to designate specific items as core variants. When you configure core variants for a product, the availability score shifts: it will be calculated exclusively based on the percentage of those core variants that are in stock, ignoring the availability of any non-core variants.

You can define core variants by assigning the value true for the isCoreVariant attribute group to at least one variant of a product. The logic will then automatically take the core variants into account to calculate variant availability. This also applies to Custom Smart Sorting Keys that use the Variant availability or Adjusted variant availability ranking factor, in either direction.

Example Calculations:

1. No Core Variants Defined
   1. Setup: A T-shirt has 5 sizes (S, M, L, XL, XXL). None are defined as core variants.
   2. Stock: 3 sizes are in stock (S, M, L), and 2 sizes are sold out (XL, XXL).
   3. Calculation: 3 available / 5 total variants.
   4. Final Score: 60%
2. Most Core Sizes are Stocked
   1. Setup: A t-shirt has 5 sizes (S, M, L, XL, XXL). Sizes M, L, and XL are defined as core variants.
   2. Stock: 2 out of the 3 core sizes are in stock (M, L). The XL size and both non-core sizes (S, XXL) are sold out.
   3. Calculation: 2 available core variants / 3 total core variants. The sold-out non-core variants are ignored.
   4. Final Score: 66% (If core variants would not be defined, this product would have scored 40%, as only 2 of its 5 total variants were available).
3. Core Sizes are Sold Out
   1. Setup: A t-shirt has 5 sizes (S, M, L, XL, XXL). Sizes M, L, and XL are defined as core variants.
   2. Stock: All 3 core sizes (M, L, XL) are sold out. Both non-core sizes (S, XXL) are perfectly stocked.
   3. Calculation: 0 available core variants / 3 total core variants.
   4. Final Score: 0% (If core variants were not defined, this product would have appeared decently stocked at 40%, since 2 out of 5 total variants were available).

Setting Up Core Variants with Attribute Mapping

While you can assign the isCoreVariant=true attribute manually to specific variants, it is recommended to use attribute mapping to improve efficiency.

Follow these steps to set it up:

1. Verify that the isCoreVariant attribute group is not assigned to any categories. If it is, please remove it from those categories before proceeding.
2. Navigate to Settings ➜ Product structure ➜ Attributes
3. Find the isCoreVariant Attribute Group and check the "Relevant for mapping" checkbox.
4. In the same menu, open the desired attribute group you use for product sizes and go to the Mapping tab.
5. Map your core sizes to the isCoreVariant=true attribute.

Custom Smart Sorting Keys

With Custom Smart Sorting Keys, you decide which signals count and how much. You create a key from ranking factors and weight each factor. You can then use the key wherever you use a system Smart Sorting Key:

• As the default sorting of a shop country or shop country category.
• In combination with a Custom Sorting Key.
• In the sortingKey parameter of the Storefront API.
• As the search tie-breaker of a shop country.

To create a Custom Smart Sorting Key, you need the permission shop__product__smart_sorting__create.

How Custom Smart Sorting Keys Work

A Custom Smart Sorting Key defines:

• The ranking factors that matter for your goal. A key needs at least one ranking factor.
• The direction of each ranking factor, for example newer or older products first.
• A weight from 1 to 5 for each ranking factor.

The weights are relative to each other. A factor with a higher weight has more influence on the product order than a factor with a lower weight. Ranking factors that you leave out have no influence.

In the SCAYLE Panel, you can preview how a Custom Smart Sorting Key orders the products of any category in any of your shop countries.

To see and edit the ranking factors of existing Custom Smart Sorting Keys, you need the permissions shop__product__smart_sorting__view and shop__product__smart_sorting__edit.

SCAYLE calculates a score for every product during indexing, the same way as for the system Smart Sorting Keys.

The system Smart Sorting Keys use the same ranking factors. You can retrieve them through the Admin API to see their ranking factors and weights, for example as a starting point for your own key.

Ranking Factors

Each ranking factor measures one signal per product and can favor either end of its scale. In the Admin API, each direction has its own weight name. The names for the opposite direction end in Inv.

How Weights Affect the Sort Order

In this example, three products differ in Sales, Recency, and Stock availability:

Two keys combine the same three ranking factors with different weights. Both keys favor more units sold (sales), newer products (recency), and well-stocked products (stockAvailability). They sort the products as follows:

• With Sales at weight 5, selling well counts the most. Both best sellers rank above the Rain Jacket, although the Rain Jacket is newer and well stocked.
• With Recency at weight 5, being new counts the most. The Rain Jacket moves to the top, although it has no sales yet.
• The Running Shoe and the Basic T-Shirt sell equally well and went live at the same time. In both keys, only Stock availability separates them, so the well-stocked Running Shoe ranks higher.

Only the relative weights count. A key with Sales 5 and Recency 5 sorts products in the same order as a key with Sales 1 and Recency 1, because in both keys the two ranking factors count equally.

Choosing Between Similar Ranking Factors

Some ranking factors measure related signals with a different emphasis.

Variant Availability or Adjusted Variant Availability

Both ranking factors measure how many of a product's variants, usually sizes, are available.

• Variant availability rewards every additional available variant until most of the product's variants are available. Use it when every additional size in stock should count.
• Adjusted variant availability mainly separates products with a broken size run from products with a good size run. Small differences between products that are already well covered, or nearly sold out, have little effect. Use it to move products with only a few sizes left further down.

Stock or Stock Availability

• Stock rewards higher stock levels. Use it when you want to move large inventory, for example to free up warehouse space.
• Stock availability separates products that have enough units to sell from products that are about to sell out. Once a product is well stocked, more units make little difference. Use it to keep nearly sold-out products away from the top positions.

Sales, Recent Sales, or Sales Acceleration

• Sales favors products that sold well over the past 30 days. Use it for established bestsellers.
• Recent sales favors products that are selling well right now, because the latest days count the most.
• Sales acceleration favors products whose sales are growing, regardless of how many units they sell. You can combine it with Recent sales, so that products with very few sales do not move to the top.

When Changes Take Effect

SCAYLE calculates Custom Smart Sorting Keys during indexing. A new key, or a change to the ranking factors or weights of an existing key, takes effect in the Storefront API after the next indexing run. See How Shop Data is Updated.

Until the next indexing run, a request that sorts by a new key returns the products sorted by product ID.

Deleting Custom Smart Sorting Keys

You can delete a Custom Smart Sorting Key at any time, even while it is in use. You need the permission shop__product__smart_sorting__delete. Deleting a key removes it from every shop, shop country, and shop country category that uses it, and from the Smart Sorting for Search tie-breaker of every shop country that uses it. You cannot change or delete system Smart Sorting Keys.

Custom Sorting

With custom sorting, you are completely flexible in ranking your products depending on your needs. You can access Custom Sortings under Shops ➜ [Shop] ➜ Products ➜ Sorting ➜ Sorting Methods ➜ Custom Sorting.

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.

Custom Sorting Key Creation

Custom product sortings are created on the global or shop country level. The following permissions are required 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:

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

Products with a higher sortValue are ranked higher in the product listing. Since descending order is the default, the highest scores claim the top slots, with lower scores following further down the page.

For the following example, the Product Listing stream would be:

1. ID = 206095: sortValue=4
2. ID = 206088: sortValue=3
3. ID = 206063: sortValue=2
4. ID = 206128: sortValue=1

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: SCAYLE Product ID, which should get a sorting value.
• application_id: Application/Shop ID for which the sorting should be used.
• sort_key: Sorting key for the product sorting.
• sort_value: Sorting value (Score) of the product for the sorting key.

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__edit you can assign a default smart sorting to the global shop level, which will apply to all categories in all countries of the respective shop directly under Shop ➜ Products ➜ Sorting ➜ Sorting Methods ➜ Smart Sorting by using the "view" icon on each Sorting Key.

You can also define a default Smart Sorting Key on shop country level. It overrides the default sorting configuration of the global shop level and only applies to the respective shop country. Assign it under Shop ➜ Products ➜ Sorting ➜ Sorting Assignment. This requires the permission shop__countries__update.

On the shop country category level, you have the possibility to further refine smart sortings category-specific.

You can assign a Custom Smart Sorting Key in the same way as a system Smart Sorting Key, as the default sorting of a shop country and on shop country categories.

Custom Sorting

Custom Sortings can be applied to categories at the 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.

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

Admin API

Product Sorting

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 Product-Sortings

JavaScriptPHPcURLJava

Copy

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

Product Sorting Parameters

Smart Sorting Keys

Use the /smart-sorting-keys endpoints to create, retrieve, update, and delete Custom Smart Sorting Keys. System Smart Sorting Keys are available through the same endpoints, read-only.

To address a single key, use its key with the key= prefix, for example key=end-of-season-clearance. Encode = as %3D when you build the URL yourself, as in the cURL examples. See Identifiers.

Create a Custom Smart Sorting Key

The following example creates a key that favors products with a high discount, high stock, and a long time in the shop, for example to clear the remaining stock at the end of a season.

JavaScriptPHPcURLJava

Copy

The response returns the created key with the status 201 Created:

json

Copy

Retrieve Smart Sorting Keys

To get a single key, use its identifier. The following example retrieves the system key scayle:v1:topseller.

JavaScriptPHPcURLJava

Copy

The response shows the ranking factors and weights of the key. System Smart Sorting Keys have no description, so the response contains no description field:

json

Copy

To get several keys, request the collection. The following example returns only Custom Smart Sorting Keys.

JavaScriptPHPcURLJava

Copy

The response contains the keys in entities and a cursor. A cursor.next of null means that there is no further page. See Pagination.

json

Copy

Update a Custom Smart Sorting Key

The request replaces the weights of the key. The key in the request body must match the key in the path, because you cannot rename a key. The following example adds Adjusted variant availability, so that products with a broken size run move down.

JavaScriptPHPcURLJava

Copy

The response returns the updated key.

Delete a Custom Smart Sorting Key

A successful deletion returns the status 204 No Content. For the effect on assignments and storefront requests, see Deleting Custom Smart Sorting Keys.

JavaScriptPHPcURLJava

Copy

Assign a Custom Smart Sorting Key to a Shop Country

You assign a Custom Smart Sorting Key the same way as a system Smart Sorting Key: set its key in the smartSortingKey field. Assigning a key that does not exist returns 400 Bad Request with the error key INVALID_SMART_SORTING_KEY.

The following example reads a shop country, sets its default Smart Sorting Key, and writes it back. See Update a Shop Country.

JavaScriptPHPcURLJava

Copy

Assign a Custom Smart Sorting Key to a Shop Country Category

The following example reads the configuration of a shop country category, sets its Smart Sorting Key, and writes the complete configuration back.

JavaScriptPHPcURLJava

Copy

Errors

Besides the general Admin API errors, the following error keys (errorKey) are specific to Smart Sorting Keys:

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.

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

TypescriptcURL

Copy

Sorting by Recency

Sorting identifier: sort=new

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

TypescriptcURL

Copy

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

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 system Smart Sorting Keys or one of your Custom 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 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.

Trending

Sorting Key: scayle:v1:trending

The Trending Smart Sorting Key:

• Highlights fast-emerging trend products by tracking recent sales growth compared to a baseline.
• Ensures customers can purchase the items by automatically deprioritizing products with low stock or variant availability.
• Works best in high-volume stores (ideally with at least 10k sales in the past 21 days) to accurately identify meaningful trend spikes.

TypescriptcURL

Copy

Sales Push

Sorting Key: scayle:v1:sales-push

The Sales Push Smart Sorting Key:

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

TypescriptcURL

Copy

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 Smart Sorting Key:

• 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 (if SCAYLE Checkout is used).

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

The Balanced Value Offerings Smart Sorting Key:

• 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 (if SCAYLE Checkout is used).

TypescriptcURL

Copy

Inventory Optimization

Sorting Key: scayle:v1:inventory-optimization

The Inventory Optimization Smart Sorting Key:

• Prioritize products with higher stock levels to optimize inventory turnover.
• Consider revenue contribution to promote high-performing products (if SCAYLE Checkout is used).
• Boost products offering greater absolute discount values.
• Highlight products with attractive discount percentages.

TypescriptcURL

Copy

Luxury Promotion

Sorting Key: scayle:v1:luxury-promotion

The Luxury Promotion Smart Sorting Key:

• Prioritize original price to highlight high-value luxury items (if SCAYLE Checkout is used).
• 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.

TypescriptcURL

Copy

Comprehensive Stock Coverage

Sorting Key: scayle:v1:stock-coverage

The Comprehensive Stock Coverage Smart Sorting Key:

• 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 (if SCAYLE Checkout is used).
• Includes discount value to highlight items offering a good deal.

TypescriptcURL

Copy

Topseller

Sorting Key: scayle:v1:topseller

The Topseller Smart Sorting Key:

• 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 (if SCAYLE Checkout is used).

TypescriptcURL

Copy

Revenue Maximization

Sorting Key: scayle:v1:revenue-max

The Revenue Maximization Smart Sorting Key:

• 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 (if SCAYLE Checkout is used).

TypescriptcURL

Copy

Recently Popular

Sorting Key: scayle:v1:recently-popular

The Recently Popular Smart Sorting Key:

• 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 (if SCAYLE Checkout is used).

TypescriptcURL

Copy

Sort by a Custom Smart Sorting Key

To sort products by a Custom Smart Sorting Key, pass its key in the sortingKey parameter. The same rules apply as for system Smart Sorting Keys, including the combination with a campaign key and the combination with a Custom Sorting Key.

TypeScriptcURL

Copy

Smart Sorting 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.

TypescriptcURL

Copy

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.

TypescriptcURL

Copy

Custom Sorting in Combination with Smart Sorting

Combined Sorting allows you to apply multiple sorting keys at the same time, combining the precision of Custom Sorting with the intelligence of Smart Sorting. When multiple sorting keys are used together, all products are ordered by the first sorting key first. Products that share the same value for the first key are then ordered by the second sorting key.

This gives you deliberate control over the products that matter most, while letting SCAYLE dynamically rank everything else, without having to manually curate your entire catalogue.

Combined Sorting can be configured at the shop country category level via the SCAYLE Panel or triggered directly through the Storefront API by passing multiple sorting keys in a single request.

Use Case: Pinning Products

One of the most common applications of Combined Sorting is product pinning ⇒ locking specific products into guaranteed top positions within a category listing, regardless of how the Smart Sorting Key would otherwise rank them.

This is particularly useful when you want to highlight:

• Sponsored products that have been agreed upon with brand or supplier partners and must be featured prominently within a category.
• High-priority items with significant business impact that should always appear at the top of the page.
• Hero products selected by your merchandising team, where top placement needs to be guaranteed independently of sales performance, recency, or stock levels.

Setting Up Combined Sorting

Via the SCAYLE Panel

Combined Sorting is configured at the shop country category level. Navigate to Shops ➜ [Shop] ➜ [Category] and assign both a Custom Sorting Key and a Smart Sorting Key to the category.

When both are configured, the following order of precedence applies:

1. Products are first sorted by their custom sorting and then by smart sorting.
2. If multiple products share the same custom sorting, those products are then sorted by the Smart Sorting Key.

Via the Storefront API

To invoke Combined Sorting directly via the Storefront API, pass multiple sorting keys as a comma-separated value in the sortingKey parameter. The keys are applied in the order they are listed.

TypescriptcURL

Copy

Once the shop indexing process is complete and the products have been sorted, the changes will be directly reflected in your Storefront Application as explained here.