Get list of banners registered for query
Lists the banners registered for a given query. Check the configuring banners documentation for a full explanation of the banner feature.
ℹ️ Migrate to Intelligent Search API v1 for HTTP caching, lower latency, and a simpler URL structure. The new endpoint is: GET Get list of banners registered for query. See the migration guide.
Permissions
This endpoint does not require authentication or permissions.
Path parameters
Format
The facets parameter follows the format: /${facetKey1}/${facetValue1}/${facetKey2}/${facetValue2}/.../${facetKeyN}/${facetValueN}.
⚠️ Required: Only the trade-policy facet is mandatory. All other facets are optional filters.
The order in which the terms appear is not relevant to the search.
You can also repeat the same facetKey several times for different values. For example: category-1/shoes/color/blue/color/red/color/yellow.
Filter combinations
When shoppers apply filters, the API combines them according to the following rules:
- Facets of the same type → OR (union): When multiple values of the same facet are applied, the API returns the union of all products matching any of those values.
- Facets of different types → AND (intersection): When different facet types are combined, the API returns only the products that satisfy all selected facet conditions simultaneously.
Negative filters (NOT operator)
To exclude a facet value, prefix the value with not: in the path segment: /{facetKey}/not:{facetValue}/. For example, color/blue/size/not:42 keeps color blue and excludes size 42. Use the same not: prefix with the facet keys and values configured in your catalog. This supports use cases such as including products in one collection but excluding another.
The NOT operator excludes specific values. The OR and AND rules in Filter combinations still describe how multiple positive facet selections combine.
Available filters
The facets parameter allows the following filters:
| facetKey | Description | Example |
|---|---|---|
| trade-policy (required) | Filter by trade policy (sales channel) using trade-policy/{tradePolicyId}. Some integrations use the salesChannel query string for the same purpose when supported. | trade-policy/2 |
| category-${n} (optional) | Filter the search by category, where n represents the category tree level (1 = department, 2 = category, 3 = subcategory, and so on). Declare the full path from the root level through every parent down to the level you need. For example, using only category-2/shirts without the category-1/... segment is incorrect. | category-1/clothing/category-2/shirts |
| brand (optional) | Filter by brand slug or identifier. | brand/acme |
| {specificationName} (optional) | Filter by a catalog specification exposed as a search filter, using {specificationName}/{specificationValue} (for example color/blue). | color/blue |
| productClusterIds (optional) | Filter by collection ID. | productClusterIds/262 |
| price (optional) | Filter by price range ${minPrice}:${maxPrice}. | trade-policy/1/color/blue/price/100:500 (with ?query=shirt on the full URL when using a text query). |
Query parameters
Search term. It can contain any character.
This parameter is named query in the API. The short form q is an alias for query and has the same semantics.
You can search for products or SKUs using specific ID types by adding search parameters (query) at the end of the store URL, respecting one of the following structures:
- Single item search: ?query=[id type]:[id_1]. Example: ?query=product:98765
- Multiple items search: ?query=[id type]:[id_1];[id_2];[id_3]. Example: ?query=product:98765;98743
⚠️ All searched IDs should be of the same type.
Search by ID
On the Intelligent Search API, search products or SKUs by ID by sending the value in the query or q query parameter on requests such as /product_search/{facets}. The {facets} path must include the required trade-policy facet and any optional filters.
- Product ID: .../product_search/trade-policy/1?query=product:98765 or .../product_search/trade-policy/1?query=product.id:98765.
- SKU ID: .../product_search/trade-policy/1?query=sku.id:12345 or .../product_search/trade-policy/1?query=sku:12345.
Supported ID types
The possible value types for the ID segment are product.id, sku.id, sku.ean, sku.reference, product.link, or id (ProductID, ProductRefID, SKUID, SKURefID, and EAN).
| ID Type | Query format | Example |
|---|---|---|
| Product ID | ?query=product:<id> or ?query=product.id:<id> | ?query=product:98765 |
| SKU ID | ?query=sku:<id> or ?query=sku.id:<id> | ?query=sku.id:12345 |
| Reference ID | ?query=sku.reference:<id> | ?query=sku.reference:REF123 |
| EAN | ?query=sku.ean:<id> | ?query=sku.ean:7891234567890 |
| Slug | ?query=product.link:<link> | ?query=product.link:blue-shirt |
Indicates the target language as a BCP 47 language code. The Intelligent Search must have indexed the account in the target language.
Response
OK