Eureka Category Merchandising API

Eureka’s Category Merchandising API allows you to curate and manage your product listing pages effectively. Tailored for various list pages like categories, sales, new arrivals, and brands, enables you to pin, boost, bury, or hide specific products as needed. You can set the rules using a visual merchandising editor to customize content for particular categories. Once you apply the rules, you can build the listing pages by making an API call based on the type of listing page and its filter.

The initial step involves sending your data in the correct format to Insider One, typically handled through system rules defined during the website mapping process.

Category Merchandising API responses are in JSON format containing product matching criteria, configured merchandising content, and available facet options for further refinement.

For merchandising rules, use Category Merchandising API instead of All Product Collections.

Requirements for Category Merchandising API

For product details, Insider One product catalog integration methods (XML, Catalog API, and Clickstream) should be created.
Data collection should be activated by the Insider One team.
Eureka should be activated by the Insider One team.
If you want to use dynamic filters (facets) and sorting in the category pages, you need to set these configurations via Eureka Settings in Insider One's InOne panel.

Endpoint

GEThttps://ineureka.api.useinsider.com/api/web/collections/{type}?cf={COLLECTION_FILTER}&p={PARTNER_ID}&l={LOCALE}&c={CURRENCY}

Visit our Postman collection to test this request.

For requests where the total URL length exceeds 2,048 characters, a POST request must be sent to the base URL, which is https://ineureka.api.useinsider.com/api/web/collections. While the HTTP protocol itself does not define an explicit maximum URL length, practical limitations exist across browsers, web servers, proxies, and load balancers.

To prevent compatibility issues and request failures, we enforce this length threshold as a precaution. Although GET requests may respond faster in some cases, it is important to switch to POST when the payload approaches or exceeds about 2,000 characters.

This ensures compliance with common platform constraints and avoids potential truncation, rejection, or undefined behavior resulting from excessively long URLs.

The only difference between GET and POST requests is that the values sent as URL parameters in GET requests must be sent as a JSON body in POST requests. For example:

{
  "cf": "COLLECTION_FILTER",
  "p": "PARTNER_ID",
  "l": "LOCALE",
  "c": "CURRENCY",
  "sid": "STRATEGY_ID"
}

When the request is sent, an authentication exception is thrown for security reasons. Therefore, when sending the request, you need to set the X-AUTH-TOKEN field in the header with the token shared with you and send the request.

Collection Types

When retrieving products from the product catalog, three different collection types help organize and filter results based on specific criteria. These collection types are:

Category Collection

The Category Collection type enables the retrieval of all products in the catalog that belong to a specific category, helping to narrow down results based on product type. For example, to get all shoes, you can retrieve products under the "Footwear" category.

Brand Collection

The Brand Collection type enables you to retrieve all products from a specific brand in the catalog, making it easy for users to access products from their preferred brands. For example, if you want to get all Nike products, you can use this option to retrieve only items from the "Nike" brand.

All Products Collection

The All Products Collection type allows you to retrieve all products in the catalog without restrictions, providing access to the entire product catalog. For example, if you want to see all products, you can use this option to retrieve all products in the catalog.

Using these collection types, you can retrieve products efficiently based on your specific needs.

Common Capabilities for All Types

Sorting

The st parameter in the request can only have one value from the predefined sorting types. Using these types, the sorting algorithm for the listed products is selected. Depending on your data, the sorting types can be active or inactive. You can view these settings on the InOne panel.

Parameter	Sorting Type
st	Relevancy
st	PriceAsc
st	PriceDesc
st	MostPopularFirst
st	BestRatedFirst
st	MostRatedFirst
st	NewestFirst
st	MostFavoriteFirst
st	MostDiscountedFirst

Filters

You can filter listed products using field names in the filter settings defined in faceting in Insider One's InOne panel.

Sample Faceting Regarding the Filter Config

Sample filter request:

&a=category~Skin~Body Lotions&a=price~5~10

In the result of this filter request, you can see the matched facets in the related property sections of items as below:

{
  "itemProperties": {
    "item_card": {
      "price": {
        "EUR": 7.75,
        ...
      },
      "category": [
        "Skin",
        "Body Lotions",
        ...
      ],
      "in_stock": 1,
      ...
    },
    ...
  },
  ...
}

The field values you can use for facet filtering are provided under data.aggregations in the result.

[
  {
    "name": "price",
    "label": "Price",
    "style": "Slider",
    "items": [
      {
        "name": "0~5",
        "min": 0.0,
        "max": 5.0
      },
      {
        "name": "5~10",
        "min": 5.0,
        "max": 10.0
      },
      ...
    ],
    "sequence": 1,
    "itemOrderType": "KeyAsc"
  },
  {
    "name": "category",
    "label": "Category",
    "style": "List",
    "items": [
      {
        "name": "Skin",
        "selected": true,
        "documentCount": 66
      },
      {
        "name": "Body Lotion",
        "selected": true,
        "documentCount": 61
      },
      ...
    ],
    "sequence": 2,
    "itemOrderType": "CountDesc"
  },
  {
    "name": "in_stock",
    "label": "In Stock",
    "style": "Checkboxes",
    "items": [
      {
        "name": "1",
        "selected": false,
        "documentCount": 12
      },
      ...
    ],
    "sequence": 3,
    "itemOrderType": "CountDesc"
  },
  ...
]

This table details the facet filter styles and their corresponding data types. Based on the specific filter style you want to implement, choose the appropriate data type.

Filter Style	Data Type
Price	Numeric
Rating	Numeric
Range	Numeric
Slider	Numeric
Checkboxes	String
List	String
Toggle	Boolean

For filters with numeric data types, such as Slider style, include only two values: min and max.

{field}~{minValue}~{maxValue}

Sample Filter Parameters

&a=brand~Neki

&a=category~Birds~Cats~Dogs

&a=price~50~100

&a=brand~Neki&a=price~50~100

Sample Responses

Parameter	Definition
status	It is the field that shows the result of the search. This field can be: - Success: Category Merchandising API response is valid. - Error: Unexpected internal server errors. - Invalid: Eureka Category Merchandising API returns a Validation Exception. The request is invalid. - BusinessException: Eureka Category Merchandising API returns a Business Exception. Details are shared in Validation Exceptions section.
data	It is the object where items, sortings, aggregations, navigations, and noResultPageText are kept as a result of a given query.
data.items	This field holds the list of properties for the returned items.
data.items.itemId	It shows the item ID. * In case there are variants of the item, the ID refers to the item to be displayed in search results. The item details are kept under data.items.itemProperties; in addition to that, all the variants, including the item displayed, are also stored in data.items.itemVariants
data.items.itemProperties.item_card	This field holds all of the fields such as name, discount, product_attributes (which includes a list of fields such as flavor, color, etc.). * In case there are price and original_price fields, they are the same unless there is a discount on this product. When there is a discount, the price field is equal to the discounted price. * These fields may vary depending on your account.
data.items.itemVariants	This field holds all of the variants of an item. The first element of the list is the item to be displayed in search results. The format of data.items.itemVariants items is the same as the data.items.itemProperties.item_card. * Variants are options of the same item that have different properties. For instance, yellow and red color options of the same t-shirt might be variants of the t-shirt. * Use of variants may be active or passive depending on your account.
data.aggregations	This field holds a list of different aggregations.
data.aggregations.name	This field holds the aggregation name.
data.aggregations.label	This field holds the aggregation label (which is for showing the name of the aggregation to the end user).
data.aggregations.style	This field holds the aggregation style. Possible values: Price, Checkboxes, Toggle, Rating, Range, Slider, List
data.aggregations.items	This field holds a list of item fields for the specified aggregation.
data.aggregations.items.name	This field holds the aggregation item name.
data.aggregations.items.label	This field holds the aggregation item label.
data.aggregations.items.min	This field holds the minimum value of the aggregation item if the aggregation style is numeric.
data.aggregations.items.max	This field holds the maximum value of the aggregation item if the aggregation style is numeric.
data.aggregations.items.selected	It is a boolean field that indicates whether the aggregation item is selected if the aggregation style is not numeric.
data.aggregations.items.documentCount	This field holds the total number of documents of the aggregation item if the aggregation style is not numeric.
data.aggregations.suffixUnit	This field holds the suffix unit for the facet values as a string. For instance, for perfume_size facets, ml is the suffixUnit (50ml - 100ml)
data.aggregations.prefixUnit	This field holds the prefix unit for the facet values as a string.
data.aggregations.sequence	This field holds the sequence of the aggregation for showing the aggregations to the end-user in the correct order.
data.aggregations.itemOrderType	This field holds the item order type of the aggregation. Possible values: KeyAsc, KeyDesc, CountDesc, CountAsc, None
data.navigation	This dictionary shows information such as pagination and total item count.
data.navigation.totalPages	This field shows how many pages are returned for a given query.
data.navigation.currentPage	This field specifies which page the returned result is.
data.navigation.totalItems	This field shows how many items are returned for a given query.
data.navigation.itemPerPage	It is the field that shows how many items are returned on each page.
data.noResultPageText	If a query does not return any results, this field is used for the empty result page. E.g., No Results found
data.sortings	It is the list where the details about sorting are kept.
data.sortings.type	It is the field where the sorting type is located. Possible sorting types: Relevancy, PriceAsc, PriceDesc, MostPopularFirst, BestRatedFirst, MostRatedFirst, NewestFirst, MostFavoriteFirst, MostDiscountedFirst
data.sortings.label	It is the label of sorting that is displayed to the end user.
data.sortings.selected	It is a boolean field that indicates whether the relevant sorting is selected.
data.defaultSortingType	It is the field where the sorting type of the recommended items is located. It is null when no active sorting is found.
partnerResources	It is the list of labels to be displayed to the end user. It provides localization flexibility based on the locale parameter sent. *Partner resources can be set from the InOne panel.
error	When there is a business exception (501), this field is filled with code and message fields.
validations	When the request is incorrect (400 Bad Request), this field is filled with an array of type and message fields.

200 Success

{ 
  "status": "Success",
  "data": {
    "items": [...],
    "aggregations": [...],
    "navigation": {...},
    "noResultPageText": "...",
    "sortings": [...]
  },
  "redirection": null,
  "partnerResources": {...},
  "error": null,
  "validations": null
}

500 Internal Server Error

{ 
  "status": "Error",
  "data": null,
  "redirection": null,
  "partnerResources": null,
  "error": {
    "code": "500 INTERNAL_SERVER_ERROR",
    "message": "..." 
  },
  "validations": null
}

400 Business Exception

You can refer to the Fail Records Messages to troubleshoot the Business Exception errors.

{ 
  "status": "BusinessException",
  "data": null,
  "redirection": null,
  "partnerResources": null,
  "error": {
    "code": "...",
    "message": "..." 
  },
  "validations": null
}

400 Validation Exception

You can refer to the Fail Records Messages to troubleshoot the Validation Exception errors.

{ 
  "status": "Invalid", 
  "data": null, 
  "redirection": null, 
  "partnerResources": null,
  "error": null,
  "validations": [
    {
      "type": "...",
      "message": "..."
    }
  ]
}

Fail Records Messages

Business Exceptions

Message	Definition	HTTP Code
AggregationStyleNotFound	Aggregation style must be provided in the partner config.	400
AggregationConfigNotFound	Aggregation configs must be provided in the partner config.	400
SortingConfigNotFound	Sorting configs must be provided in the partner config	400
SortingFieldNotFound	Sorting field must be provided in the partner config.	400
InvalidPriceAggregationStyle	Incorrect style for price aggregation is provided in the partner config.	400
PartnerConfigNotFound	Partner config cannot be gathered from the cache.	400
AggregationResultNotFound	Unexpected aggregation results were received according to aggregation configs.	400

Validation Exceptions

Message	Definition	HTTP Code
PartnerIdNotFound	p parameter is not provided in the request	400
LocaleNotFound	l parameter is not provided in the request	400
LocaleInvalidFormat	Wrong locale format is provided in the request	400
CurrencyNotFound	c parameter is not provided in the request	400
CurrencyInvalidFormat	Wrong currency format is provided in the request	400
CollectionFilterNotFound	Collection filter cf is not provided	400
CollectionFilterInvalidFormat	Collection filter format is invalid	400
InvalidCollectionFilter	Collection filter must not be given with AllProducts Collection Type	400
CollectionInvalidLength	Collection filter must contain a number of characters between 2 and 280	400
PaginationFromInvalidValue	Wrong pf value is provided in the request	400
PaginationSizeInvalidValue	Wrong ps value is provided in the request	400
AggregationNameNotFound	Aggregation name must be provided in the request	400
AggregationItemsNotFound	Aggregation items must be provided in the request	400
SortingTypeInvalid	Sorting type is not valid	400