How to

Get product

Retrieve detailed information about a single product using Geins Merchant API

Prerequisites

Merchant API key
Product ID or product alias

Goals

Fetch product information for a product detail page (PDP)

Architecture at a glance

Query product with ID or alias → Get complete product details → Display on product page

APIs used

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

Step-by-step

Get product by alias

Fetch a product using its URL-friendly alias (slug). This is the most common method for product detail pages.

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

Request example

query getProduct(
    $alias: String!
    $channelId: String
    $languageId: String
    $marketId: String
) {
    product(
        alias: $alias
        channelId: $channelId
        languageId: $languageId
        marketId: $marketId
    ) {
        productId
        alias
        name
        articleNumber
        canonicalUrl
        skus {
          skuId
          name
          stock {
            totalStock
          }
        }
        texts {
            text1
            text2
            text3
        }
        brand {
            name
            alias
            canonicalUrl
        }
        productImages {
            fileName
        }
        unitPrice {
            sellingPriceIncVat
            sellingPriceExVat
            sellingPriceIncVatFormatted
            regularPriceIncVat
            regularPriceIncVatFormatted
            isDiscounted
        }
        totalStock {
            totalStock
            inStock
        }
        variantGroup {
            variants {
                productId
                alias
                label
                name
                primaryImage
                stock {
                    inStock
                }
            }
        }
        parameterGroups {
            name
            parameters {
                name
                value
            }
        }
    }
}

{
    "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 getProduct($alias: String!, $channelId: String, $languageId: String, $marketId: String) { product(alias: $alias, channelId: $channelId, languageId: $languageId, marketId: $marketId) { productId alias name articleNumber canonicalUrl skus { skuId name stock { totalStock } } texts { text1 text2 text3 } brand { name alias canonicalUrl } productImages { fileName } unitPrice { sellingPriceIncVat sellingPriceExVat sellingPriceIncVatFormatted regularPriceIncVat regularPriceIncVatFormatted isDiscounted } totalStock { totalStock inStock } variantGroup { variants { productId alias label name primaryImage stock { inStock } } } parameterGroups { name parameters { name value } } } }","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": {
        "product": {
            "productId": 1234,
            "alias": "{PRODUCT_ALIAS}",
            "name": "Premium Wireless Headphones",
            "articleNumber": "WH-1000XM5",
            "canonicalUrl": "/p/premium-wireless-headphones",
            "skus": [
                {
                    "skuId": 5678,
                    "name": "Premium Wireless Headphones - Black",
                    "stock": {
                        "totalStock": 47
                    }
                }
            ],
            "texts": {
                "text1": "<p>These premium wireless headphones deliver exceptional audio quality with industry-leading noise cancellation. Perfect for music lovers and professionals alike.</p>",
                "text2": "Experience superior sound quality with active noise cancellation.",
                "text3": null
            },
            "brand": {
                "name": "Acme Audio",
                "alias": "acme-audio",
                "canonicalUrl": "/b/acme-audio"
            },
            "productImages": [
                {
                    "fileName": "headphones-black-front.jpg"
                },
                {
                    "fileName": "headphones-black-side.jpg"
                }
            ],
            "unitPrice": {
                "sellingPriceIncVat": 299.00,
                "sellingPriceExVat": 239.20,
                "sellingPriceIncVatFormatted": "$299.00",
                "regularPriceIncVat": 349.00,
                "regularPriceIncVatFormatted": "$349.00",
                "isDiscounted": true
            },
            "totalStock": {
                "totalStock": 47,
                "inStock": 47
            },
            "variantGroup": {
                "variants": [
                    {
                        "productId": 1235,
                        "alias": "premium-wireless-headphones-white",
                        "label": "White",
                        "name": "Premium Wireless Headphones - White",
                        "primaryImage": "headphones-white-front.jpg",
                        "stock": {
                            "inStock": true
                        }
                    }
                ]
            },
            "parameterGroups": [
                {
                    "name": "Specifications",
                    "parameters": [
                        {
                            "name": "Color",
                            "value": "Black"
                        },
                        {
                            "name": "Connectivity",
                            "value": "Bluetooth 5.2"
                        },
                        {
                            "name": "Battery Life",
                            "value": "30 hours"
                        }
                    ]
                }
            ]
        }
    }
}

Get product by ID

Alternatively, fetch a product using its numeric product ID. Useful when you have the ID from another query or database.

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

Request example

query getProductById(
    $productId: Int!
    $channelId: String
    $languageId: String
    $marketId: String
) {
    product(
        productId: $productId
        channelId: $channelId
        languageId: $languageId
        marketId: $marketId
    ) {
        productId
        alias
        name
    }
}

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

{
    "productId": 1234,
    "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 getProductById($productId: Int!, $channelId: String, $languageId: String, $marketId: String) { product(productId: $productId, channelId: $channelId, languageId: $languageId, marketId: $marketId) { productId alias name } }","variables":{"productId":1234,"channelId":"{CHANNEL_ID}","languageId":"{LANGUAGE_ID}","marketId":"{MARKET_ID}"}}'

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

Using productId when you meant to use alias - the query accepts both but alias is more common for URLs
Requesting too many fields - only request fields you actually need for better performance
Not handling null responses - product may not exist or be unavailable in the specified market
Forgetting to check skus.stock.totalStock before allowing purchases. Observe that stock levels are managed at the SKU level. The totalStock field on the product level provides an aggregate stock level but individual SKUs may have different stock statuses.

Get list of CMS pages

Retrieve and display a list of CMS pages using tags to filter content with Geins Merchant API

Get product categories

Fetch category tree via Merchant API and render top-level and nested categories.