Merchant JS API



This guide describes Findify's Merchant Javascript Library API, which allows you to create a custom integration with mostly any Javascript framework, to control the feedback and handle requests from our server. If you are looking for a customization guide - have a look at our DevTools.

Accessing the Findify Instance

(window.findifyCallbacks = window.findifyCallbacks || []).push(function(findify) {
  console.log(findify) // <- The Findify instance

The findifyCallbacks array, including callbacks, will be resolved right after the Findify library is loaded and the initial widgets are rendered. The functions pushed to this array after their initialization will be resolved immediately.


findify.config - Findify's configuration is made of an immutable structure containing a global setup of your store's settings. Widgets are picking specific parts based on its type or "slot" (e.g.: recommendations). In case you want to create a manual recommendation widget, the configuration would not be picked automatically, so you need to apply it manually.
You can find an example configuration over here: Example configuration

const widgetConfiguration = findify.config.getIn(['features', 'search', '#home-findify-rec-2']);
findify.widget.attach('#node', 'search', widgetConfiguration.toJS())


findify.widgets - contains methods to manage widgets

findify.widgets.attach([node], [type], [config])

Will create a custom widget and render it in HTML node.

  • node - CSS selector or DOM node where the widget will be placed
  • type - The type of a widget (could be "Autocomplete", "Search", "Recommendation")
  • config - Extends the feature configuration. Also, you can provide a "widgetKey" to be able to access this widget by a key.


Will completely remove a widget.

  • widgetKey - unique widget key or specified one


List of created widgets on the page.


Returns a widget by key.

  • widgetKey - unique widget key or specified one


Returns an array of widgets with a specified type

  • type - either Search, Recommendation or Autocomplete

Widget Properties

  • type - widget type
  • key - unique widget key
  • node - node where widget is rendered in
  • agent - @findify/agent instance reference
  • config - widget configuration [sample]


findify.listen and findify.emit - cross-widget events, you can subscribe to a widget lifecycle or emit your own event.

findify.listen(callback([type], [*props], [*props]))

  • type - event type
  • props - event specific properties

findify.emit([type], [props])

  • type - event type
  • props - event specific properties

Analytics - instance of @findify/analytics


findify.utils - list of helper functions and validations

  • history - custom window history API instance
  • collectionPath - normalized window.location.pathname
  • isCollection(collections[array], slot[string]) - check if current page is collection page
  • isSearch() - check if current page is Search Page
  • getQuery() - returns an object with proper query parameters of an url
  • buildQuery(query[object]) - creates a string from a query object
  • redirectToSearch(searchTerm[string]) - will redirect to the search page with required query parameters
  • scrollTo(element[string|node], offset[number]) - will scroll to a specific element +- offset(default 0)