How to

Get related products

Fetch related, similar, and accessory products to display product recommendations using Geins Merchant API

Goals

Retrieve related products for product detail pages
Display product recommendations (accessories, similar products, related items)
Understand relation types and their use cases

Architecture at a glance

Query relatedProducts with product alias → Get related products with relation types

APIs used

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

Step-by-step

Fetch all related products for a specific product using its alias. Related products include accessories, similar items, and other related recommendations.

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

Request example

query getRelatedProducts(
    $alias: String!
    $channelId: String
    $languageId: String
    $marketId: String
) {
    relatedProducts(
        alias: $alias
        channelId: $channelId
        languageId: $languageId
        marketId: $marketId
    ) {
        alias
        name
        canonicalUrl
        relationType
        primaryImage
        brand {
            name
            alias
        }
        unitPrice {
            sellingPriceIncVat
            sellingPriceIncVatFormatted
            regularPriceIncVat
            regularPriceIncVatFormatted
            isDiscounted
        }
        productImages {
            fileName
        }
        primaryCategory {
            categoryId
            name
            alias
        }
    }
}

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

{
    "alias": "{PRODUCT_ALIAS}",
    "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 getRelatedProducts($alias: String!, $channelId: String, $languageId: String, $marketId: String) { relatedProducts(alias: $alias, channelId: $channelId, languageId: $languageId, marketId: $marketId) { alias name canonicalUrl relationType primaryImage brand { name alias } unitPrice { sellingPriceIncVat sellingPriceIncVatFormatted regularPriceIncVat regularPriceIncVatFormatted isDiscounted } productImages { fileName } primaryCategory { categoryId name alias } } }","variables":{"alias":"{PRODUCT_ALIAS}","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": {
        "relatedProducts": [
            {
                "alias": "headphone-carrying-case",
                "name": "Premium Headphone Carrying Case",
                "canonicalUrl": "/p/headphone-carrying-case",
                "relationType": "ACCESSORIES",
                "primaryImage": "headphone-case.jpg",
                "brand": {
                    "name": "AudioPro",
                    "alias": "audiopro"
                },
                "unitPrice": {
                    "sellingPriceIncVat": 29.99,
                    "sellingPriceIncVatFormatted": "$29.99",
                    "regularPriceIncVat": 29.99,
                    "regularPriceIncVatFormatted": "$29.99",
                    "isDiscounted": false
                },
                "productImages": [
                    {
                        "fileName": "headphone-case.jpg"
                    }
                ],
                "primaryCategory": {
                    "categoryId": 45,
                    "name": "Accessories",
                    "alias": "accessories"
                }
            },
            {
                "alias": "wireless-earbuds-pro",
                "name": "Wireless Earbuds Pro",
                "canonicalUrl": "/p/wireless-earbuds-pro",
                "relationType": "SIMILAR",
                "primaryImage": "earbuds-pro.jpg",
                "brand": {
                    "name": "AudioPro",
                    "alias": "audiopro"
                },
                "unitPrice": {
                    "sellingPriceIncVat": 199.99,
                    "sellingPriceIncVatFormatted": "$199.99",
                    "regularPriceIncVat": 249.99,
                    "regularPriceIncVatFormatted": "$249.99",
                    "isDiscounted": true
                },
                "productImages": [
                    {
                        "fileName": "earbuds-pro.jpg"
                    }
                ],
                "primaryCategory": {
                    "categoryId": 12,
                    "name": "Headphones",
                    "alias": "headphones"
                }
            },
            {
                "alias": "audio-cable-premium",
                "name": "Premium Audio Cable 3.5mm",
                "canonicalUrl": "/p/audio-cable-premium",
                "relationType": "ACCESSORIES",
                "primaryImage": "audio-cable.jpg",
                "brand": {
                    "name": "TechConnect",
                    "alias": "techconnect"
                },
                "unitPrice": {
                    "sellingPriceIncVat": 14.99,
                    "sellingPriceIncVatFormatted": "$14.99",
                    "regularPriceIncVat": 14.99,
                    "regularPriceIncVatFormatted": "$14.99",
                    "isDiscounted": false
                },
                "productImages": [
                    {
                        "fileName": "audio-cable.jpg"
                    }
                ],
                "primaryCategory": {
                    "categoryId": 45,
                    "name": "Accessories",
                    "alias": "accessories"
                }
            }
        ]
    }
}

Understanding relation types

The relationType field indicates how each product relates to the main product. This helps you organize recommendations into meaningful sections.

Administrate available relation types using the Mgmt API.

Example relation types

ACCESSORIES - Products that complement or enhance the main product (e.g., cases, cables, chargers)
SIMILAR - Alternative products with similar features or in the same category
RELATED - General related products that might interest the customer

Group related products by relationType in your UI to create distinct recommendation sections like "Accessories", "Similar Products", or "Customers Also Viewed".

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.

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

Not grouping products by relation type - displaying all related products together can be confusing
Showing related products when none exist - always check if the array is empty before rendering
Fetching too many fields - only request the fields you need

Get redirects mapping

Retrieve URL and slug (alias) redirects to manage and audit your site's redirection rules.

Get user data

Retrieve authenticated user profile information including address and preferences using Geins Merchant API