Sort products

Prerequisites

• Merchant API key

Goals

• Sort product listings by different criteria
• Understand available sort types and their use cases

Architecture at a glance

• Query products with sort parameter → Get products in desired order

APIs used

• Merchant API: https://merchantapi.geins.io/graphql

Step-by-step

query sortProducts(
    $categoryAlias: String
    $sort: SortType
    $skip: Int
    $take: Int
    $channelId: String
    $languageId: String
    $marketId: String
) {
    products(
        categoryAlias: $categoryAlias
        skip: $skip
        take: $take
        filter: { 
            sort: $sort
        }
        channelId: $channelId
        languageId: $languageId
        marketId: $marketId
    ) {
        products {
            productId
            name
            canonicalUrl
            productImages {
                fileName
            }
            unitPrice {
                sellingPriceIncVat
                sellingPriceIncVatFormatted
            }
        }
        count
    }
}

{
    "Accept": "application/json",
    "X-ApiKey": "{MERCHANT_API_KEY}"
}

{
    "categoryAlias": "electronics",
    "sort": "PRICE",
    "skip": 0,
    "take": 12,
    "channelId": "{CHANNEL_ID}",
    "languageId": "{LANGUAGE_ID}",
    "marketId": "{MARKET_ID}"
}

curl -X POST https://merchantapi.geins.io/graphql \
    -H "Accept: application/json" \
    -H "Content-Type: application/json" \
    -H "X-ApiKey: {MERCHANT_API_KEY}" \
    -d '{"query":"query sortProducts($categoryAlias: String, $sort: SortType, $skip: Int, $take: Int, $channelId: String, $languageId: String, $marketId: String) { products(categoryAlias: $categoryAlias, skip: $skip, take: $take, filter: { sort: $sort }, channelId: $channelId, languageId: $languageId, marketId: $marketId) { products { productId name canonicalUrl productImages { fileName } unitPrice { sellingPriceIncVat sellingPriceIncVatFormatted } } count } }","variables":{"categoryAlias":"electronics","sort":"PRICE","skip":0,"take":12,"channelId":"{CHANNEL_ID}","languageId":"{LANGUAGE_ID}","marketId":"{MARKET_ID}"}}'

{
    "data": {
        "products": {
            "products": [
                {
                    "productId": 101,
                    "name": "Budget Headphones",
                    "canonicalUrl": "/p/budget-headphones",
                    "productImages": [
                        {
                            "fileName": "budget-headphones.jpg"
                        }
                    ],
                    "unitPrice": {
                        "sellingPriceIncVat": 29.99,
                        "sellingPriceIncVatFormatted": "$29.99"
                    }
                },
                {
                    "productId": 102,
                    "name": "Mid-Range Headphones",
                    "canonicalUrl": "/p/mid-range-headphones",
                    "productImages": [
                        {
                            "fileName": "mid-range.jpg"
                        }
                    ],
                    "unitPrice": {
                        "sellingPriceIncVat": 99.99,
                        "sellingPriceIncVatFormatted": "$99.99"
                    }
                }
            ],
            "count": 24
        }
    }
}

Available sort types

The SortType enum provides the following sorting options:

Common sort types

• PRICE - Sort by price (lowest to highest)
• PRICE_DESC - Sort by price (highest to lowest)
• MOST_SOLD - Sort by popularity (best sellers first)
• LATEST - Sort by newest products first
• ALPHABETICAL - Sort alphabetically by name (A-Z)
• ALPHABETICAL_DESC - Sort alphabetically by name (Z-A)
• RELEVANCE - Sort by search relevance (use with text search)

Stock-based sorting

• AVAILABLE_STOCK - Sort by available stock (lowest to highest)
• AVAILABLE_STOCK_DESC - Sort by available stock (highest to lowest)
• TOTAL_STOCK - Sort by total stock (lowest to highest)
• TOTAL_STOCK_DESC - Sort by total stock (highest to lowest)

Other sort types

• BRAND - Sort by brand name
• VOTES - Sort by customer ratings/votes
• FACET_ORDER - Sort by facet order
• NONE - No sorting applied

Custom sort types

• CUSTOM_1 to CUSTOM_5 - Custom sort. These are simple sort values that can be set on products via the Mgmt API backend for specific use cases.

Multi-market support

All queries support optional parameters for multi-market functionality:

• channelId: Target specific sales channels
• languageId: Set content language
• marketId: Target specific markets

Authenticated access

While authentication is not required for this query, including a JWT bearer token in the Authorization header can provide personalized results based on the authenticated user's context, for example personalized pricing.

To include authentication, add the JWT bearer token to your request headers:

"Authorization": "Bearer {JWT_TOKEN}"

Common pitfalls

• Not providing a default sort option - users expect some order, even if it's just MOST_SOLD
• Using RELEVANCE without text search - this sort type only works with search queries
• Forgetting to update sort when switching between search and browse modes
• Not communicating the current sort order to users in the UI