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.

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 sortings in the category pages, you need to set these configurations via Eureka Settings in the 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}

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

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

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 the retrieval of all products in the catalog without any 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.

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.

For the filters with numeric data types, such as Slider style, there should be 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

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

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

400 Validation Exception

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

Fail Records Messages

• Business Exceptions

• Validation Exceptions