Use CMS area filters
Overview
Learn how to fetch a CMS area with specific content using the url argument in the widgetArea query.
Prerequisites
- Merchant API key
- An existing CMS family with at least one area and applied filters
- Canonical URL for the page (for example, "/p/shoes/shoe-blue" or "/c/shoes")
Goal
- Resolve and return the appropriate widget collection for an area on a specific URL, leveraging automatic filter resolution
Architecture at a glance
- Call
widgetAreawithurl→ The API infers filters from the URL → Receive specific CMS content
Example
Pass an existing canonical URL as the url argument to automatically resolve the correct area content.
{CANONICAL_URL} must point to a product list page, a product page, a category page, a brand page or a campaign page.Request example
query widgetArea(
$family: String
$areaName: String
$url: String
$displaySetting: String
$customerType: CustomerType
$channelId: String
$languageId: String
$marketId: String
) {
widgetArea(
family: $family
areaName: $areaName
url: $url
displaySetting: $displaySetting
customerType: $customerType
channelId: $channelId
languageId: $languageId
marketId: $marketId
) {
tags
containers {
layout
design
widgets {
name
configuration
images { fileName }
}
}
}
}
{
"Accept": "application/json",
"X-ApiKey": "{MERCHANT_API_KEY}"
}
{
"url": "{CANONICAL_URL}",
"family": "{CMS_FAMILY}",
"areaName": "{CMS_AREA_NAME}",
"displaySetting": "desktop",
"customerType": "PERSON",
"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 widgetArea($family: String!, $areaName: String!, $url: String!, $displaySetting: String, $channelId: String, $languageId: String, $marketId: String) { widgetArea(family: $family, areaName: $areaName, url: $url, displaySetting: $displaySetting, customerType: $customerType, channelId: $channelId, languageId: $languageId, marketId: $marketId) { tags containers { layout design widgets { name configuration images { fileName } } } } }","variables":{"family":"{CMS_FAMILY}","areaName":"{CMS_AREA_NAME}","url":"{CANONICAL_URL}","displaySetting":"desktop","customerType":"PERSON","channelId":"{CHANNEL_ID}","languageId":"{LANGUAGE_ID}","marketId":"{MARKET_ID}"}}'
channelId, languageId, and marketId arguments are optional and can be left out to use default values.Response example
200 OK{
"data": {
"widgetArea": {
"tags": ["page"],
"containers": [
{
"layout": "full",
"design": "default",
"widgets": [
{
"name": "ContentBlock",
"configuration": "{...}",
"images": [{"fileName": "image.jpg"}]
}
]
}
]
}
}
}
Use case: Show a widget on a specific category page
If you want a Banner to appear only on the "Shoes" category page:
- In your Geins CMS, add a filter to the area that targets the "Shoes" category.
- Call
widgetAreawithurlset to the canonical URL of that page (for example, "/c/shoes"). - The API returns the Banner only for that URL; other pages won’t include it.
Options
Display setting
Provide displaySetting (for example, desktop or mobile) to return device-specific containers and widgets.
Customer type
You can provide a customerType argument (PERSON or ORGANIZATION) to fetch widgets and content tailored to specific customer segments. This allows for personalized experiences based on whether the user is a business or an individual consumer.
Channel, Language, and Market
The query also supports optional parameters for multi-market support:
channelId, languageId, and marketId in the "how to"-article 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 or restricted content.
To include authentication, add the JWT bearer token to your request headers:
"Authorization": "Bearer {JWT_TOKEN}"