How to

Search products

Search products using text search and sort by relevance with Geins Merchant API

Goals

Search products using text search
Sort search results by relevance

Architecture at a glance

Enter search text → Query products with filter → Get sorted results

APIs used

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

Use the products query with filter.searchText to search for products by name, description, article number, or other searchable fields. Add sort: RELEVANCE to return the most relevant results first.

Try it out in the GraphQL Playground using the query, headers and variables below.

Request example

query searchProducts(
    $searchText: String!
    $skip: Int
    $take: Int
    $channelId: String
    $languageId: String
    $marketId: String
) {
    products(
        skip: $skip
        take: $take
        filter: { 
            searchText: $searchText
            sort: RELEVANCE
        }
        channelId: $channelId
        languageId: $languageId
        marketId: $marketId
    ) {
        products {
            productId
            alias
            name
            canonicalUrl
            articleNumber
            productImages {
                fileName
            }
            unitPrice {
                sellingPriceIncVat
                sellingPriceIncVatFormatted
            }
            brand {
                name
                alias
            }
        }
        count
    }
}

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

{
    "searchText": "wireless headphones",
    "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 searchProducts($searchText: String!, $skip: Int, $take: Int, $channelId: String, $languageId: String, $marketId: String) { products(skip: $skip, take: $take, filter: { searchText: $searchText, sort: RELEVANCE }, channelId: $channelId, languageId: $languageId, marketId: $marketId) { products { productId alias name canonicalUrl articleNumber productImages { fileName } unitPrice { sellingPriceIncVat sellingPriceIncVatFormatted } brand { name alias } } count } }","variables":{"searchText":"wireless headphones","skip":0,"take":12,"channelId":"{CHANNEL_ID}","languageId":"{LANGUAGE_ID}","marketId":"{MARKET_ID}"}}'

The channelId, languageId, and marketId arguments are optional and can be left out to use default values.

Response example

200 OK

response.json

{
    "data": {
        "products": {
            "products": [
                {
                    "productId": 1234,
                    "alias": "{PRODUCT_ALIAS}",
                    "name": "Premium Wireless Headphones",
                    "canonicalUrl": "/p/premium-wireless-headphones",
                    "articleNumber": "WH-1000XM5",
                    "productImages": [
                        {
                            "fileName": "headphones-black.jpg"
                        }
                    ],
                    "unitPrice": {
                        "sellingPriceIncVat": 299.00,
                        "sellingPriceIncVatFormatted": "$299.00"
                    },
                    "brand": {
                        "name": "Acme Audio",
                        "alias": "acme-audio"
                    }
                }
            ],
            "count": 47
        }
    }
}

Pagination

Use skip and take parameters for pagination:

skip: Number of products to skip (default: 0, max: 6000)
take: Number of products to return (default: 20, max: 200)
count: Total number of matching products (use for pagination controls)

To calculate page numbers: currentPage = (skip / take) + 1 and totalPages = Math.ceil(count / take)

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

Read more about channelId, languageId, and marketId in the how-to about using multi-market support.

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}"

Read more about obtaining and using JWT tokens in the guide about the authentication flow.

Common pitfalls

Empty search results - ensure searchText is not too specific or check if products exist
Slow queries - limit the number of fields requested and use appropriate take values
Case sensitivity - search is case-insensitive, no need to normalize input

Reset user password

Complete password reset flow for users using Geins Merchant API

Sort products

Sort product listings by price, popularity, name, stock levels, and more using Geins Merchant API