How to integrate a custom Product Sorting

Introduction

Product sorting is an important feature in e-commerce, familiar to customers and crucial for a shop's usability. While SCAYLE offers basic filters and#smart-sorting, sometimes you need custom sorting based on specific criteria. This tutorial delves into how SCAYLE enables bespoke product sorting.

Imagine that you want to sort products to highlight those with a higher sales potential at the top, while items like nearly out-of-stock products follow. Sort based on brand, price, product lifespan, and other factors. Different sorting for special categories, like sales, may also be required.

Additionally, specific scenarios require unique sorting methods. For instance, sale categories or specialized collections may need a fixed sorting order for their products. Keep in mind, SCAYLE doesn’t provide a Business Intelligence (BI) tool to execute these sorting calculations.

Prerequisites

Before exploring this tutorial, ensure you have a fundamental understanding of SCAYLE’s Admin API, Storefront API, and the general approach to how SCAYLE structures shops and their shop countries.

How SCAYLE’s sorting works

SCAYLE provides pre-defined sorting options applicable in both ascending and descending orders. Use the sort parameter in your products endpoint calls to SCAYLE’s Storefront API. Here’s a summary of the available sorting types:

If none of the existing sorting options meet your needs, SCAYLE provides the flexibility to create custom sorting keys. These custom sorting keys allow you to define a unique set of sorting values, enabling you to arrange your products according to your preferences.

Think of a sorting key as a descriptive label. It's a string that groups together a set of sorting values. This helps you categorize and manage your products effectively. A sorting value is a positive number that determines the ranking of a product within a specific sorting key category

Additionally, sorting values are defined per shop country, giving you the option to have different sortings per country while using the same sorting key. Each shop can have as many sorting keys as required but per sorting key, only one sorting value can be defined per product-shop-country-combination. Based on the assignment you can request SCAYLE’s Storefront API products endpoint to get the sorting per country shop and sorting key.

When using your own custom sortingKeys the sort parameter will be ignored.

How to add new sortings

To create new sortings in SCAYLE you’ll need to create new sorting keys and assign products with a sorting value to those keys. Creating new sorting keys is straight forward. SCAYLE's backend automatically checks for the existence of sorting keys. If the keys you're entering don't exist already, SCAYLE will create them.

It's important to maintain consistent naming conventions when adding new values to the same sorting key. This includes case sensitivity and special characters like underscores.

Adding sorting values can be achieved in multiple ways depending on your setup. Typical scenarios include:

1. Using a backend system: This system calculates and provides the sorting values for products.
2. Using data files: Employing processes that handle data in formats like xlsx or CSV, especially when the Admin API is not an option.
3. Manual processing: For a select number of products, a fully manual process is implemented.

In the following section, we'll explore various methods for adding sorting keys and values in SCAYLE.

Adding sorting values via Admin API

If you have a backend system that automatically calculates the score of each product, and you want to seamlessly integrate that score into SCAYLE without manual effort, you should leverage SCAYLE's Admin API.

The create or update product sortings endpoint allows you to push multiple product sorting values in a single array at once. This feature allows you to mix different products, shops, and sorting keys within a single API request. It's important to note that higher sorting values will result in products being displayed first on your shop's frontend. Consider the following example payload, where different products with different sorting keys are combined in a single request.

Additionally, you have the flexibility to use the productReferenceKey instead of the internal productId.

json

Copy

If you leave out the country code, the provided sorting values will be applied across all countries simultaneously.

In cases where your shop setup includes multiple shops for the same country (e.g., two shops for Switzerland to cater to both German and French languages), and you include "countryCode": "CH" as part of the payload, the specified sorting key will only be applied to the first shop.

Adding sorting values via bulk import

If you're not using the Admin API but need to sort a large product range, consider the bulk import feature via the SCAYLE Panel. With this import, you’re able to upload multiple sorting values for different combinations of products, shops (applications_ids), and sorting keys. Let's take a closer look at the structure of the import page, and we’ll provide you with a few examples.

Adding sorting values via shop configuration

For a limited product range or to overwrite sorting values for specific items, we recommend you using the SCAYLE Panel. Here, you can create sorting keys and assign values in a way typical of SCAYLE's user-friendly interface. Detailed guidance is available in the SCAYLE Panel documentation found here.

Putting everything into practice

Let's apply this with three sorting keys: sorting_default, sorting_sales, and sorting_special. Imagine a product range labeled product1 through product5 (with corresponding IDs 1 to 5) in the Fashion Store, available in both DE and AT. Each product can have unique sorting values for each sorting key and shop country, but it's not mandatory for all products to have a value. Here's an example of how such an assignment might look:

Remember, products without assigned sorting values for certain keys are automatically considered as having a value of 0.

With different sorting values set, the next step is to request them through SCAYLE’s Storefront API GET products endpoint. Below you’ll find examples showing the key results.

Get the sale sorting for the DE shop

Given the following:

• shopId: 10001
• sortingKey: sorting_sales

Your API request::

{{baseUrl}}/v1/products?sortingKey=sorting_sales&shopId=10001\

Result:

json

Copy

Get the sale sorting for the AT shop

Given the following:

• shopId: 10002
• sortingKey: sorting_sales

Your API request:

{{baseUrl}}/v1/products?sortingKey=sorting_sales&shopId=10002

Result:

json

Copy

Note that the same sorting key can result in different orderings, as sorting values may vary per country for each product.

Get the special sorting for the DE shop

Given the following:

• shopId: 10001
• sortingKey: sorting_special

Your API request:

{{baseUrl}}/v1/products?sortingKey=sorting_special&shopId=10001

Result:

json

Copy

Here, both product5 and product3 have no set sorting value, effectively treated as 0. If two products share the same value, SCAYLE displays the one with the higher id first, hence why product5 comes before product3.

Best Practices

• Automate with Admin API: We recommend using the Admin API for automated creation of sorting values. This approach minimizes manual work and potential human error.
• Sorting strategy: Implement a default sorting key for general needs and restrict the amount of special sortings to minimize updating efforts, while keeping the shop product listing pages up to date.
• Country code consideration: Exclude the country code for uniform sorting across countries, resulting in faster imports and streamlined data management.
• Category custom data: Utilize category custom data for multiple sorting keys. Define different shop category sortings either through the Admin API or SCAYLE Panel. Adding custom data to your country shop allows the frontend to automatically retrieve and apply the correct sorting key. Like sorting_special for product data requests, eliminating frequent code adjustments.
• BI integration: If sorting is based on BI or similar tools, either supply these values to SCAYLE or incorporate a third-party solution. For extensive sorting variations, like individual customer sortings, consider a specialized third-party program.