How to

Get product categories

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

Learn how to fetch product categories from the Merchant API and render them in navigation or filters.

Prerequisites

Merchant API key
Channel/market/language context (defaults are supported)

Goals

Retrieve categories (top-level or nested)
Build a simple tree for navigation or filtering

Architecture at a glance

Query categories → Render list/tree

APIs used

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

Step-by-step

Query categories

Use parentCategoryId: 0 to only fetch top-level categories. Omiting the parameter fetches all categories. Set it to a specific category ID to get its children.

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

Request example

query categories(
  $parentCategoryId: Int
  $channelId: String
  $languageId: String
  $marketId: String
) {
  categories(
    parentCategoryId: $parentCategoryId
    channelId: $channelId
    languageId: $languageId
    marketId: $marketId
  ) {
    categoryId
    parentCategoryId
    name
    alias
    canonicalUrl
  }
}

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

// Fetching only top-level categories
{ 
  "parentCategoryId": 0,
  "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 categories($parentCategoryId:Int,$channelId:String,$languageId:String,$marketId:String,$includeHidden:Boolean){ categories(parentCategoryId:$parentCategoryId,channelId:$channelId,languageId:$languageId,marketId:$marketId,includeHidden:$includeHidden){ categoryId parentCategoryId name alias canonicalUrl }}","variables":{"parentCategoryId":0,"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": {
    "categories": [
      { 
        "categoryId": 1, 
        "parentCategoryId": 0, 
        "name": "Men", 
        "alias": "men", 
        "canonicalUrl": "/c/men" 
      }
    ]
  }
}

Validation

Top-level: parentCategoryId: 0 returns only root categories
A known parent ID returns its children
Names and canonicalUrl match storefront navigation

For optimal UX, cache categories in your application state/store to speed up navigation and rendering.

Options

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.

Get product

Retrieve detailed information about a single product using Geins Merchant API

Get redirects mapping

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